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About This Manual 


This manual describes CYBIL, the implementation language of the 
CONTROL DATA® Network Operating System/Virtual Environment 
(NOS/VE). 

Audience 

This manual is written as a reference for CYBIL programmers. It assumes 
that you understand NOS/VE and System Command Language (SCL) 
concepts as presented in the SCL Language Definition manual and the SCL 
System Interface manual. You will also need to be familiar with the CYBIL 
file manuals (described next under Organization) in order to perform input to 
and output from a CYBIL program. 

Organization 

This manual is organized by topic, based on elements of the CYBIL 
language. The first chapter introduces the basic elements of the language 
and refers you to the chapter in which each is further described. 

The CYBIL Manual Set 


This manual is part of the CYBIL manual set. Besides this manual, the 
CYBIL manual set includes the following: 

• The CYBIL System Interface manual, which describes the CYBIL 
procedures that pertain to command language services and processing, 
program services and management, task and job management services, 
condition processing, message generation, and interstate communication. 

• The CYBIL File Management manual, which describes the CYBIL 
procedures that assign files to device classes, specify attributes for files, 
and perform file opening, closing, and copying. 

• The CYBIL Sequential and Byte Addressable Files manual, which 
describes the CYBIL procedures that perform data manipulation on 
sequential and byte addressable files. 

• The CYBIL Keyed-File and Sort/Merge Interfaces manual, which 
describes: 

- The interface to NOS/VE keyed-files (that is, files having the indexed- 
sequential and direct-access file organizations). 

- The interface to NOS/VE Sort/Merge (which is used to sort records or 
merge files of sorted records). 
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CONVENTIONS 


Conventions 

Within the formats for declarations, type specifications, and statements 
shown in this manual, uppercase letters represent reserved words; they must 
appear exactly as shown. Lowercase letters represent names and values that 
you supply. 

Required parameters are shown in bold type. Optional parameters are shown 
in italics and are enclosed by braces, as in: 

{ PACKED j 

If the parameter is optional and can be repeated any number of times, it is 
also followed by several periods, as in'. 

{name }... 

For example, the notation {digit} means zero digits or one digit can appear; 
{digit}... means zero, one, or more digits can appear. Braces also indicate that 
the enclosed parameters and reserved words are used together. For example, 

{offset MOD base } 

is considered a single parameter. Except for the braces and periods 
indicating repetition, all other symbols shown in a format must be included. 

Numbers are assumed to be decimal unless otherwise noted. 

In examples that show interactive terminal sessions, user input is printed in 
blue. System output is printed in black. 

New features, as well as changes, deletions, and additions to information in 
this manual, are indicated by vertical bars in the margins or by a dot near 
the page number if more than half the page is affected. 
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ADDITIONAL RELATED MANUALS 


Additional Related Manuals 

The related manuals listed on page 2 include the manuals you should be 
familiar with to this point, and which manuals you may want to read 
following this one. In addition, you may want to have a copy of the CDC® 
CYBER 170/180 Models 810, 815, 825, 830, 835, 845, 855, and 990 (Virtual 
State) Hardware Reference Manual, Volume II, publication number 
60458890. You do not need the hardware manual to use the information in 
this CYBIL manual, but it is useful because it includes more detail about the 
hardware and, in particular, the hardware instructions used in certain 
CYBIL procedures described in this manual. 

The Math Library manual, publication number 60486513, describes the 
mathematical routines available in the Math Library. These routines can be 
accessed by CYBIL programs. 

The Diagnostic Messages for NOS/VE manual, publication number 
60464613, documents diagnostic messages generated by NOS/VE. 


Ordering Manuals 

Control Data manuals are available through Control Data sales offices or 
through: 

Control Data Corporation 
Literature Distribution Services 
308 North Dale Street 
St. Paul, Minnesota 55103 


Submitting Comments 

The last page of this manual is a comment sheet. Please use it to give us your 
opinion of the manual’s usability, to suggest specific improvements, and to 
report technical or typographical errors. If the comment sheet has already 
been used, you can mail your comments to: 

Control Data Corporation 
Publications and Graphics Division ARH219 
4201 Lexington Avenue North 
St. Paul, Minnesota 55126-6198 

Please indicate whether you would like a written response. 

Additionally, if you have access to SOLVER, an online facility for reporting 
problems, you can use it to submit comments about the manual. When 
entering your comments, use CIL as the product identifier. 


Revision D 


About This Manual 9 




Introduction 


1 


This chapter introduces the basic elements of a CYBIL program and refers 
you to the chapter in which each is further described. 






Introduction 


A CYBIL program consists of two kinds of elements: declarations and 
statements. Declarations describe the data to be used in the program. 
Statements describe the actions to be performed on the data. 

Declarations and statements are made up of predefined reserved words and 
user-defined names and values. The way you form these elements is 
described in chapter 2, as is the general structure for designing a CYBIL 
program. 

Data can be either constant or variable. You can use the constant value itself 
or give it a name using the constant declaration (CONST). Variables are 
named, initialized, and given certain characteristics with the variable 
declaration (VAR). 

One of the characteristics of a variable is its type, for example, integer or 
character. You can use CYBIL’s predefined types or define your own types. 
To define a new type or redefine an existing type with a new name, you use 
the type declaration (TYPE). Once you have defined a type, CYBIL will treat 
it as a standard data type; you can specify your new type name as a valid 
type in a variable declaration and CYBIL will perform standard type 
checking on it. You can also declare where you want certain variables to 
reside by defining an area called a section, which can be a read-only section 
or a read/write section. This is done with the SECTION declaration. All of 
these data-related declarations are described in chapter 3. 

Many standard types are available, including integers, floating-point 
numbers, characters, and boolean values, to name a few. In addition, you 
can use combinations of the standard types to define your own data types, 
for example, a record that contains several fields. The next few paragraphs 
summarize the types that are predefined by CYBIL. They are described in 
detail in chapter 4. 

Among the basic types are scalar types, that is, those that have a specific 
order. Besides integer, character, and boolean values, you can declare an 
ordinal type in which you define the elements and their order. You can also 
specify a subrange of any of the scalar types by giving a lower and upper 
bound. Floating-point (real) numbers are also available. A cell, which 
represents the smallest addressable unit of memory, can be specified as a 
type. A pointer is a type that points to a variable, allowing you to access the 
variable by location rather than by name. These are the basic types: scalar, 
floating point, cell, and pointer. With these basic types you can construct the 
structured types: strings, arrays, records, and sets. 
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A string is a sequence of characters. You can reference a portion of a string 
(called a substring) or a single character within a string. An array is a 
structure that contains components all of the same type. The components of 
an array have a specific order and each one can be referenced individually. A 
record is a structure that contains a fixed number of fields, which may be of 
different types. Each field has a unique name within the record and can be 
referenced individually. You can also declare a variant record that has 
several possible variations (variants). The current value of a field common to 
all variants, or the latest assignment to a specific variant field determines 
which of the variants should be used for each execution. A set is a structure 
that contains elements of a single type. Yet unlike an array, elements in a set 
have no order and individual elements cannot be referenced. A set can be 
operated on only as a whole. 

Storage types are structures to which variables can be added, referenced, and 
deleted under explicit program control using a set of storage management 
statements. The two storage types are sequences and heaps. 

All of the types mentioned above are considered fixed types; that is, there is a 
definite size associated with each one when it is declared. If you want to 
delay specifying a size until execution time, you can declare it as an 
adaptable type. Then, sometime during execution, you assign a fixed size or 
value to the type. A string, array, record, sequence, or heap can be adaptable. 

All of these types are described in chapter 4. 

Statements define the actions to be performed on the data you’ve defined. 

The assignment statement changes the value of a variable. Structured 
statements contain and control the execution of a list of statements. The 
BEGIN statement unconditionally executes a statement list. The WHILE, 
FOR, and REPEAT statements control repetitive executions of a statement 
list. 

Control statements control the flow of execution. The IF and CASE 
statements execute one of a set of statement lists based on the evaluation of a 
given expression or the value of a specific variable. CYCLE, EXIT, and 
RETURN statements stop execution of a statement list and transfer control 
to another place in the program. 

Storage management statements allocate, access, and release variables in 
sequences (using the RESET and NEXT statements), heaps (using the 
RESET, ALLOCATE, and FREE statements), and the run-time stack (using 
the PUSH statement). 

All of the preceding statements are described in detail in chapter 5, along 
with the operands and operators that can be used in expressions within 
statements and declarations. 
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Statements can appear within a program (as described in chapter 2), a 
function, or a procedure. 

A function is a list of statements, optionally preceded by a list of 
declarations. It is known by a unique name and can be called by that name 
from elsewhere in the program. A function performs some calculation and 
returns a value that takes the place of the function reference. There are many 
standard functions defined in CYBIL and you can also create your own. 
Standard functions and rules for forming your own functions are described 
in chapter 6. 

A procedure, like a function, is a list of statements, optionally preceded by a 
list of declarations. It also is known by a unique name and can be called by 
that name from elsewhere in the program. A procedure performs specific 
operations and may or may not return values to existing variables. You can 
use the standard procedures and also define your own. Chapter 7 describes 
the standard procedures and rules for forming your own procedures. 

Chapter 8 describes the CYT3IL command and the FORMAT_CYBIL_ 
SOURCE command. You can use the CYBIL command to call the CYBIL 
compiler, tell it which files to use for input and output, and specify what kind 
of listing you want. You use the FORMAT_CYBIL_ SOURCE command to 
reformat CYBIL source code. Chapter 8 also describes directives that are 
available at compilation time to specify listing options, run-time options, the 
layout of the source text and resulting object listing, and what specific 
portions of the source text to compile. 

Chapter 9 describes the Debug utility, which aids you in debugging CYBIL 
programs at a source code level or machine code level, in either interactive or 
batch mode. 

In summary, chapters 2 through 7 describe the elements within a CYBIL 
program. Chapter 8 describes the command and directives that control how 
the program is actually compiled. Chapter 9 describes debugging 
capabilities. 

Procedures that perform input to and output from CYBIL programs are 
described in the CYBIL File Management manual, the CYBIL Sequential 
and Byte Addressable Files manual, and the CYBIL Keyed-File and 
Sort/Merge Interfaces manual. 
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H| Program Structure 


This chapter describes how to form the individual elements used within a 
program and how to structure the program itself. 
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Program Structure 


2 


This chapter describes how to form the individual elements used within a 
program and how to structure the program itself. 


Elements Within a Program 

Valid Characters 

The characters that can be used within a program are those in the ASCII 
character set that have graphic representations (that is, can be printed). This 
character set is included in appendix B. It contains uppercase and lowercase 
letters. In names that you define, you can use uppercase and lowercase 
letters interchangeably. For example, the name LOOP _ COUNT is 
equivalent to the name loop _ count. 


CYBIL-Defined Elements 

CYBIL has predefined meanings for many words and symbols. You cannot 
redefine or use these words and symbols for other purposes. 

A complete list of CYBIL reserved words is given in appendix C. In the 
formats for declarations, type specifications, and statements shown in this 
manual, reserved words are shown in uppercase letters. 

The following list includes the reserved symbols and a brief description of 
the purpose of each. They are discussed in more detail throughout this 
manual. 

Symbol _ Purpose _ 

+, -, *, /, =, <, <=, These symbols are primarily operators used 

>, >=, <>,:=, (,) in expressions. They are discussed in chapter 5. 

; The semicolon separates individual declarations and 

statements. 

: The colon is used in declarations as described in chapter 

3. 

, The comma separates repeated parameters or other 

elements. 

A single period indicates a reference to a field within a 
record as described in chapter 4. 


( Continued) 
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(Continued.) 

Symbol _ Purpose _ 

Two consecutive periods indicate a subrange as 
described in chapter 4. 

The circumflex indicates a pointer reference as 
described in chapter 4. 

Apostrophes delimit strings. 

[ ] Brackets enclose array subscripts, indefinite value 

constructors, and set value constructors as described in 
chapter 4. 

{} Braces delimit comments. (Within the formats shown in 

this manual, they are also used to enclose optional 
parameters.) 

? or ?? A single question mark or a pair of consecutive question 

marks indicate compile-time statements and directives 
as described in chapter 8. 


User-Defined Elements 

Names 

You define the names for elements, such as constants, variables, types, 
procedures, and so on, that you use within a program. A name-' 

• Can be from 1 to 31 characters in length. 

• Can consist of letters, digits, and the special characters # (number sign), 
@ (commercial at sign), _ (underline), and $ (dollar sign).f 

• Must begin with a letter. (There is an exception to this rule for system- 
defined functions and procedures that begin with the # or $ character.) 

• Cannot contain spaces. 


t NOS/VE often uses $ in its predefined names. To keep from matching a 
system reserved name, avoid using $ in the names you define. 


2-2 CYBIL Language Definition 


Revision A 







ELEMENTS WITHIN A PROGRAM 


In the formats included in this manual, names that you supply are shown in 
lowercase letters. Within a program, however, there is no distinction between 
uppercase and lowercase letters. The name my_file is identical to the name 
My _ File. 

There is considerable flexibility in forming names, so you should make them 
as descriptive as possible to promote readability and maintainability of the 
program. For example, LAST_ FILE _ ACCESSED is more obvious than 
LASTFIL. 

Examples: 

Valid Names _ Invalid Names _ 

SUM ARRAY 

REGISTER#3 FILES&POSITIONS 

POINTERTABLE 2ND 

The va ,; d names need no explanation. Among the invalid names, ARRAY 
cannot L used because it is a reserved word; FILES&POSITIONS contains 
an invalic -haracter (the ampersand); and 2ND does not begin with a letter. 


Constants 

A constant is a fixed value. It is known at compilation time and does not 
change throughout the execution of a program. It can be an integer, 
character, boolean, ordinal, floating-point number, pointer, or string. 

Integer constants can be binary, octal, decimal, or hexadecimal. The base is 
specified by enclosing the radix in parentheses following the integer, as 
follows: 

integer (radix) 

Examples are 1011(2) and 19A(16). If the radix is omitted, the integer is 
assumed to be decimal. Integer constants must start with a digit; therefore, 0 
must precede any hexadecimal constant that would otherwise begin with a 
letter, for example, 0FF(16). Negative integer constants must be preceded by 
a minus sign. Positive integer constants can be preceded by a plus sign but 
need not be. 

Integer constants range in value from -(2® 3 -l) to 2 63 -l; that is, 
-7FFFFFFFFFFFFFFF hexadecimal through 7FFFFFFFFFFFFFFF 
hexadecimal. 

A character constant can be any single character in the ASCII character set. 
The character is enclosed in apostrophes in the following form: 

’character’ 

Examples are ’A’ and ’?’. The apostrophe character itself is specified by a 
pair of apostrophes. 
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A boolean constant can be either FALSE or TRUE, each having its usual 
meaning. 

An ordinal constant is an element of an ordinal type that you have defined. 
For further information, refer to Ordinal under Scalar Types in chapter 4. 

Floating-point (real) constants can be written in either decimal notation or 
scientific notation. A real number written in decimal notation contains a 
decimal point and at least one digit on each side, for example, 5.123 or 
-72.18. If the number is positive, the sign is optional; if negative, the sign is 
required. 

A real number written in scientific notation is represented by a number (the 
coefficient), which is multiplied by a power of 10 (the exponent) in the form: 

coefficientEexponent 

The prefix E is read as ’’times 10 to the power of for example, 

5.1E6 

is 5.1 times 10 to the power of 6, or 5,100,000. The decimal point in the 
coefficient is optional. A decimal point cannot appear in the exponent; it 
must be a whole number. If the coefficient or exponent is positive, the sign is 
optional; if negative, the sign is required. 

The pointer constant is NIL. It indicates an unassigned pointer. For CYBIL 
on NOS/VE, a pointer is represented partially by an address called the 
process virtual address (PVA). The PVA is represented as a packed record 
consisting of three fields: the ring number, segment number, and byte offset. 
To indicate the NIL pointer constant internally, CYBIL sets these three 
fields to OF hexadecimal, OFFF hexadecimal, and 80000000 hexadecimal, 
respectively. NIL can be assigned to a pointer of any type. 
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String constants consist of one or more characters enclosed in apostrophes in 
the form: 

’string’ 

An example is ’USER1234’, a string of eight characters. An apostrophe in a 
string constant is specified by a pair of apostrophes, for example, ’DON'T. 

String constants can be concatenated by using the reserved word CAT, as in: 

’characters_l’ CAT ’characters_2’ 

The result is the string ’characters_lcharacters_2’. The CAT operation 
cannot be used with string variables. 

A string constant can be empty, that is, a null string; for example, 
str ■' = 

assigns a null string to the string constant STR. As a result of this 
statement, the length of STR is set to zero. 

You cannot reference parts (substrings) of string constants. 
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Constant Expressions 

Expressions are combinations of operands and operators that are evaluated 
to find scalar or string type values. In a constant expression, the operands 
must be constants, names of constants (that you declare using the constant 
declaration described in chapter 3), or other constant expressions within 
parentheses. Computation is done at compile time and the resulting value 
used in the same way a constant is used. 

The general rules for forming and evaluating expressions are described 
under Expressions in chapter 5. These rules apply to constant expressions 
with the following exceptions: 

• Constant expressions must be simple expressions; terms involving 
relational operators must be delimited with parentheses. 

• The only functions allowed as factors in constant expressions are the 
$INTEGER, $CHAR, SUCC, and PRED functions with constant 
expressions as arguments. 

• Substring references are not allowed. 


Syntax 

The exact syntax of the language is shown in the formats of individual 

declarations and statements described in the remainder of this manual. The 

following paragraphs discuss general syntax rules. 

Spaces 

Spaces can be used freely in programs with the following exceptions: 

• Names and reserved words cannot contain embedded spaces. Normally, 
constants cannot contain spaces either, but a character constant or string 
constant can. 

• A name, reserved word, or constant cannot be split over two lines; it must 
appear completely on one line. 

• Names, reserved words, and constants must be separated from each other 
by at least one space, or one of the other delimiters such as a parenthesis 
or comma. 

For further information, refer to Spacing later in this chapter. 
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Comments 

Comments can be used in a program anywhere that spaces can be used 
(except in string constants). They are printed in the source listing but 
otherwise are ignored by the compiler. 

A comment is enclosed in left and right braces: {). It can contain any 
character except the right brace (}). To extend a comment over several lines, 
repeat the left brace ({) at the beginning of each line. If the right brace is 
omitted at the end of the comment, the compiler ends it automatically at the 
end of the line. 

Example: 

{this comment 
{appears on 
{several lines.> 

Within this manual, the formats for declarations, type specifications, and 
statements use braces to indicate an optional parameter. 


Punctuation 

A semicolon separates individual declarations and statements. It must be 
included at the end of almost every declaration and statement. The single 
exception is MODEND which can, but need not, end with a semicolon if it is 
the last occurrence of MODEND in a compilation. Punctuation for specific 
declarations and statements is shown in the formats in the following 
chapters. 

Two consecutive semicolons indicate an empty statement, which the 
compiler ignores. Spacing between the semicolons in this case is 
unimportant. 


Spacing 

Declarations and statements can start in any column. In this manual, 
indentations are used in examples to improve readability. It is recommended 
that similar conventions be used in your programs to aid in debugging and 
documentation for yourself and other users. 

The LEFT and RIGHT directives, described in chapter 8, can be used at 
compilation time to specify the left and right margins of the source text. All 
source text outside of those margins is then ignored. A warning diagnostic is 
issued for every line that exceeds the specified right margin. 

A name, reserved word, or constant cannot be split over two lines; each must 
appear completely on one line. 
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Structure of a Program 

Module Structure 

The basic unit that can be compiled is a module and, optionally, compile-time 
statements and directives. A module can, but need not, contain a program. 
Use this general structure for a module: 

MODULE module_name; 
declarations 

PROGRAM program _ name; 
declarations 
statements 

PROCEND program _ name; 

MODEND module_name; 

Declarations can be constant, type, variable, section, function, and procedure 
declarations. A module can contain any number and combination of 
declarations, but it can contain at most one program. The program contains 
the code (that is, the statements) that are actually executed. The required 
module and program declarations are described later in this chapter. 

The structure within a module determines the scope of the elements you 
declare within it. 


Scope 

The scope of an element you declare, such as a variable, function, or 
procedure, is the area of code where you can refer to the element and it will 
be recognized. Scope is determined by the way the program and procedures 
are positioned in a module and where the elements are declared. 

In terms of scope, the programs, procedures, and functions are often referred 
to as blocks (that is, blocks of code). Generally, if an element is declared 
within a block, its scope is just that block. Outside the block, the element is 
unknown and references to it are not valid. A variable declared within a 
block is said to be local to the block and is called a local variable. 

An element declared at the module level (that is, one that is not declared 
within a program, procedure, or function) has a scope of the entire module. It 
can be referred to anywhere within the module. A variable declared at the 
module level is said to be global and is called a global variable. 

A block can contain one or more subordinate blocks. A variable declared in 
an outer block can always be referenced in a subordinate block. However, if a 
subordinate block declares an element of the same name, the new declaration 
applies while inside that block. Figure 2-1 illustrates these rules. 
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BLOCK 1 

A DECLARATION 


BLOCK 2 
B DECLARATION 


BLOCK 3 

C DECLARATION 
D DECLARATION 

BLOCK 4 
D DECLARATION 


4 - 


Variable A can be referred to anywhere 
in block 1, including blocks 2, 3, and 4. 


Variable B can be referred to only in 
block 2. 


Variables C and D can be referred to 
anywhere in blocks 3 and 4. 


However, block 4 again declares a 
variable named D. This second 
declaration identifies a different 
variable D and is in effect within 
block 4 only. Outside of block 4, 
yet within block 3, the original 
declaration for D applies. 


Figure 2-1. Scope of Variables Within a Block Structure 

Storage space is allocated for a variable when the block in which it is 
declared is entered. Space is released when an exit is made from the block. 
Because space is allocated and released automatically, these variables are 
called automatic variables. You can specify that storage for a variable 
remains throughout execution by including the STATIC attribute when you 
declare the variable. A variable declared in this way is called a static 
variable. A global variable is always static. Because it is declared at the 
outermost level of a module (consider the module to be a block), storage for a 
global variable is allocated throughout execution of the module (or block). 
For further information on automatic and static variables, refer to Variable 
Declaration in chapter 3. 

The one exception to the preceding rules is an element declared with the 
XDCL (externally declared) attribute. This attribute means the element is 
declared in one module but can be referred to in another. In this case, the 
loader handles the links between modules. For further information on the 
XDCL attribute, refer to chapter 3. 
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Module Declaration 

The module declaration marks the beginning of a module. MODEND marks 
the end of a module. A module can contain at most one program and any 
combination of type, constant, variable, section, function, and procedure 
declarations. If two or more modules are compiled and linked together for 
execution, there can be only one program declaration in all the linked 
modules. 

Use this format for a module declaration: 

MODULE name;t 
name 

The name of the module. 

Use this format for MODEND: 

MODEND[ name }; 
name 

The name of the module. This parameter is optional. If used, the name 
must be the same as that specified in the module declaration. 

When compiling more than one module, a semicolon is required after each 
occurrence of MODEND except the last one. There it is not required but is 
recommended. 

Examples: 

The following example shows a module named ONE that contains various 
declarations and a program named MAIN. The module name and semicolon 
could be omitted following MODEND, but it is recommended that you 
include both. 

MODULE one; 

declarations 

PROGRAM main; 

declarations 

statements 
PROCEND main; 

MODEND one; 


f Some variations of CYBIL available on other operating systems allow an 
additional option, the alias name, in a module declaration. If included in a 
CYBIL program run on NOS/VE, this parameter is ignored. 
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The following example shows a compilation consisting of three modules 
named ONE, TWO, and THREE. All three modules can be compiled and the 
resulting object modules linked together to form a single object module that 
can then be executed. For readability, the module names are included in all 
occurrences of MODEND. The semicolon could be left off the last occurrence 
of MODEND, but it is a good practice to include it. 

MODULE one; 

declarations/statements 
MODEND one; 

MODULE two; 

decLarations/statements 
MODEND two; 

MODULE three; 

declarations/statements 
MODEND three; 
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Program Declaration 

The program declaration marks the beginning of a program. The end of a 
program is marked by a PROCEND statement. A program can contain any 
combination of type, constant, variable, section, function, and procedure 
declarations, and any statements. If two or more modules are compiled and 
linked together for execution, there can be only one program declaration in 
the linked modules. 

Use this format for a program declaration: 

PROGRAM name {(formal-parameters )};+ 
name 

The name of the program. 

formal-parameters 

One or more optional parameters included if the program is to be called 
by the operating system. They can be in the form 

VAR name {.name }...: type 
{.name {.name}... '■ type}... 

and/or 

name {.name }...: type 
{.name {.name}... •' type}... 

where name is the name of the parameter and type is the type of the 
parameter, that is, a predefined type (described in chapter 4) or a user- 
defined type (described in chapter 3). 

The first form is called a reference parameter; its value can be changed 
during execution of the program. The second form is called a value 
parameter; its value cannot be changed by the program. Both kinds of 
parameters can appear in the formal parameter list; if so, they must be 
separated by semicolons (for example, I: INTEGER; VAR A: CHAR). 
Reference and value parameters are discussed in more detail later in 
this chapter. 


t Some variations of CYBIL available on other operating systems allow an 
additional option, the alias name, in a program declaration. If included in a 
CYBIL program run on NOS/VE, this parameter is ignored. 
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The optional parameter list is included if a CYBIL program is to be called by 
the operating system. It allows the system to pass values (for example, a 
string that represents a command) to a CYBIL program. For further 
information on passing parameters from the operating system, refer to the 
CYBIL System Interface manual. 

When the system calls a program, it includes parameters called actual 
parameters in the call. The values of those actual parameters replace the 
formal parameters in the parameter list one-for-one based on position; that is, 
the first actual parameter replaces the first formal parameter, and so on. 
Wherever the formal parameters appear in statements within the program, 
the values of the corresponding actual parameters are substituted. For every 
formal parameter in the program declaration, there must be a corresponding 
actual parameter. 

When a reference parameter is used, the formal parameter represents the 
corresponding actual parameter throughout execution of the program. Thus, 
an assignment to a formal parameter changes the variable that was passed 
as the corresponding actual parameter. An actual parameter that 
corresponds to a formal reference parameter must be addressable. A formal 
reference parameter can be of any type. 

When a value parameter is used, the formal parameter takes on the value of 
the corresponding actual parameter. However, the program cannot change a 
value parameter by assigning a value to it or specifying it as an actual 
reference parameter to a procedure or function. A formal value parameter 
can be of any type except a heap, or an array or record that contains a heap. 
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Use this format for PROCEND: 

PROCEND { name j; 
name 

The name of the program. This parameter is optional. If used, the 
name must be the same as that specified in the program declaration. 

Example: 

The following example shows a program named MAIN that contains various 
declarations, including a procedure named SUB_l: 

PROGRAM main; 

declarations 

PROCEDURE sub_1; 

declarations 

statements 
PROCEND subj; 
statements 
PROCEND main; 
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This chapter describes how you declare constant and variable data types and 
new data types. It also describes how you specify a particular section in 
which to group data. 
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This chapter describes the constant declaration, which defines a name for a 
value that never changes; the variable declaration, which defines a name for 
a value that can change; and the type declaration, which defines a new type 
of data and gives a name to that type. In addition, it also describes the 
section declaration, which groups variables that share common access 
characteristics. 


Constant Declaration 

A constant, as described in chapter 2, is a fixed value that is known at 
compile time and doesn’t change during execution. A constant declaration 
allows you to associate a name with a value and use that name instead of the 
actual constant value. This provides greater readability because the name 
can be descriptive of the constant. Constant declarations also provide greater 
maintainability because the constant value need only be changed in one 
place, the constant declaration, not every place it is used in the code. 

Use this format for a constant declaration: 

CONST name = value { ,name = value}...; 

name 

The name associated with the constant value, 
value 

The constant value. It can be an integer, character, boolean, ordinal, 
floating-point, pointer, string, or constant expression. Rules for 
forming these values are given under Constants and under Constant 
Expressions in chapter 2. 

You can write several constant declarations, each declaring a single 
constant, or a single declaration declaring several constants where each 
name = value combination is separated by a comma. 

Type is not specified in a constant declaration. The type of the constant is 
the same as the type of the value assigned to it. 

If used, an expression is evaluated during compilation. The expression itself 
can contain other constants. 
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Examples: 

Rather than repeat the value of pi throughout a program, you can use a 
constant declaration to assign a descriptive name (in this case, PI) to the 
value and use that name in subsequent expressions and operations. The 
constant declaration is: 

CONST 

pi = 3.1415927; 

The following example shows a constant declaration containing several 
different types: 

CONST 

first = 1, 

Last = 80, 
hex = 0a8(16), 
bit_pattern = 10110101(2), 
fp_number = 1.2e3, 
stop_character = 
continue = TRUE, 
message = 'end of Line', 
last_pointer = NIL, 
length = last - first, 
result =(1*2) DIV 3; 

Each constant has the same type as the value assigned to it. For example, 
FIRST and LAST are integer types, as is LENGTH, which is the result of an 
expression containing integers. Notice that the value of HEX begins with a 0 
because integers must begin with a digit. 
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Variable Declaration 

A variable is an element within a program whose value can change during 
execution. The name of the variable stays the same; it is only the value 
contained in the variable that changes. To use a variable, you must declare 
it. 

Use this format for a variable declaration: 

VAR name {.name}... • {[attributes]} type {•'= initial_ualue] 

{.name {.name}... '{[attributes]} type {•'= initial_value }}...;f 

name 

The name of the variable. Specifying more than one name indicates 
that all of the named variables will have the characteristics that follow 
(attributes, type, and initial_value). 

attributes 

One or more of the following attributes. If you specify more than one, 
separate them with commas. 

READ 

Access attribute specifying that the variable is a read-only variable; 
the compiler checks to ensure that the value of the variable is not 
changed. If you specify READ, you must also specify an initial 
value. 

XDCL 

Scope attribute specifying that the variable is declared in this 
module but can be referenced from another module. 

XREF 

Scope attribute specifying that the variable is declared in another 
module but can be referenced from this module. 


t Some variations of CYBIL available on other operating systems allow an 
additional option, the alias name, in a variable declaration. If included in a 
CYBIL program run on NOS/VE, this parameter is ignored. 
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#GATEt 

Scope attribute that allows the variable to be accessed by a 
procedure at a higher ring level. This attribute is undefined for 
variable declarations. However, if you specify #GATE, you must 
also specify the XDCL attribute. 

STATIC 

Storage attribute specifying that storage space for the variable is 
allocated at load time and remains when control exits from the 
block. Static storage is assumed when any attributes are specified. 

section _ name 

Storage attribute specifying the name of the user-defined section in 
which the variable resides. A variable in a section that is defined as 
read-only is protected by hardware, as opposed to software. The 
section name and its read/write attributes must be declared using 
the section declaration (discussed later in this chapter). 

Attributes are described in more detail later in this chapter. 

The attributes parameter is optional. If omitted, CYBIL assumes the 
variable can be read and written; can be referenced only within the 
block where it is created; and, unless it is declared at the outermost 
level of a module, is automatic (that is, storage for the variable is 
allocated only during execution of the block in which the variable is 
declared). 

type 

Data type defining the values that the variable can have. Only values 
within this data type are allowed. Types are described in chapter 4. 

initial _value 

Initial value assigned to the variable. Specify a constant expression, 
an indefinite value constructor (described under Initialization later in 
this chapter), or a pointer to a global procedure. Only a static variable 
can be assigned an initial value. Initialization is discussed later in this 
chapter. 

This parameter is optional. If omitted, the variable is undefined and 
filled with the loader’s preset value. 


t This attribute is not supported on variations of CYBIL available on other 
operating systems. 
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Any variable referenced in a program must be declared with the VAR 
declaration. A variable can be declared only once at each block level 
although it can be redefined in another block or in a contained (nested) block. 

The type assigned to a variable defines the range of values it can take on 
and also the operations, functions, and procedures that can use it. CYBIL 
checks to ensure that the operations performed on variables are compatible 
with their types. 

Examples-' 

The following declarations define a variable named SCORES that can be 
any integer number, a variable named STATUS that can be either of the 
boolean values FALSE or TRUE, and two variables named ALPHA1 and 
ALPHA2 that can be characters: 

VAR 

scores: integer; 

VAR 

status: boolean; 

VAR 

alphal: char; 

VAR 

alpha2: char; 

The declarations for the two character type variables, ALPHA1 and 
ALPHA2, could be combined as follows-' 

VAR 

alphal, 
alpha2: char; 

To combine all of the variables in one declaration, you could use: 

VAR 

scores: integer, 
status: boolean, 
alphal, 
alpha2: char; 
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Attributes 

Attributes control three characteristics of a variable: 

Access - whether the variable can be both read and written 
Scope - where within the program the variable can be referenced 
Storage - when and where the variable is stored 


Access 

The access attribute that you can specify is READ. A variable declared with 
the READ attribute can only be read. It must be initialized in the declaration 
and cannot be assigned another value later. It is called a read-only variable. 
If the READ attribute is omitted, CYBIL assumes the variable can be both 
read and written (changed). 

The READ attribute is enforced by software; that is, the compiler checks to 
ensure that the value of a variable does not change. The READ attribute 
alone does not mean that the variable is actually in a read-only section.f To 
do that, you must specify the name of a read-only section as declared in a 
section declaration (described later in this chapter). 

A variable with the READ attribute specified is assumed to be static. (For 
further information on static variables, refer to Storage later in this chapter.) 
You can use a read-only variable as an actual parameter in a procedure call 
only if the corresponding formal parameter is a value parameter; that is, a 
read-only variable can be passed to a procedure only if the procedure makes 
no attempt to assign a value to it. (Procedure parameters are described in 
chapter 7.) 

A read-only variable is similar to a constant, but can’t always be used in the 
same places. For example, the initial value that you can assign to a variable 
(as described earlier in this chapter) must be a constant expression, an 
indefinite value constructor, or a pointer to a global procedure. In this case, 
even though a read-only variable has a constant value, you cannot use it in 
place of a constant expression. Also, as mentioned in chapter 2, you cannot 
reference a substring of a constant. You can, however, reference a substring 
of a variable and, thus, a read-only variable. There are other differences 
similar to these. The descriptions in this manual state explicitly whether 
constants and/or variables can be used. 


t A read-only section is a hardware feature. Data that resides in a physical 
area of the machine designated as a read-only section is protected by 
hardware, not by software. This feature is described in further detail in 
volume II of the virtual state hardware reference manual. 
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Examples: 

In this example the variable DEBUG is a read-only variable set to the 
constant value of TRUE. NUMBER can be read and written. 

VAR 

debug: CREADI boolean := TRUE, 
number: integer; 

The following example illustrates a difference between constants and read¬ 
only variables. To declare a string type, you must specify the length of the 
string in parentheses following its name. As defined in chapter 4, the length 
must be a positive, integer constant expression. 

CONST 

string_size_1 = 5; 

VAR 

string_size_2: CREADT integer := 5, 
string - !: string (string_size_1), 
string2: string (string_size_2); 

The declaration of STRING1 is valid; the length of the string is 5, which is 
the value of the constant STRING_SIZE_1. However, STRING2 is invalid; 
even though STRING_SIZE_2 does not change in value, it is still a variable 
and cannot be used in place of a constant expression. 


Scope 

The scope attributes define the part or parts of a module to which a variable 
declaration applies. If you don’t include any scope attributes in the 
declaration, the scope of a variable is the block in which it is declared. A 
variable declared in an outermost block applies to that block and all the 
blocks it contains. However, a variable declared even at the outermost level 
of a module cannot be used outside of that module. Use the scope attributes, 
XDCL and XREF, to extend the scope of a variable so that it can be shared 
among modules. 

To use the same variable in different modules, you must specify the XDCL 
and XREF attributes. The XDCL attribute indicates that the variable being 
declared can be referenced from other modules. The XREF attribute indicates 
that the variable is declared in another module. When the loader loads 
modules, it resolves variable declarations so that each XDCL variable is 
allocated static storage and the XREF variable shares the same space. This 
is known as satisfying externals. The loader issues an error if an XREF 
variable does not have a corresponding XDCL variable. In one compilation 
unit or group of units that will be combined for execution, a specific variable 
can have only one declaration that contains the XDCL attribute. 
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Declarations for a shared variable must match except for initialization. A 
variable declared with the XDCL attribute can be initialized and have 
different values assigned during program execution. A variable declared 
with the XREF attribute cannot be initialized but can be assigned values. 

If you declare any attributes, the variable is assumed to be static in storage. 
If you don’t declare any attributes, the variable is assumed to be automatic, 
unless you declare it at the outermost level of the module. (A variable 
declared at the outermost level is always static.) 

Example: 

Assume the following two modules have been compiled. When the loader 
loads the resulting object modules and satisfies externals, it allocates storage 
to FLAG, an XDCL variable, and initializes it to FALSE. When the loader 
finds the XREF variable FLAG in module TWO, it assigns the same storage. 
Thus, references to FLAG from either module refer to the same storage 
location. 

MODULE one; 

VAR 

flag: CXDCLD boolean := FALSE; 

MODEND one; 

MODULE two; 

VAR 

flag: CXREF] boolean; 

MODEND two; 
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Storage 

The storage attributes determine when storage is allocated and where 
storage is allocated. 


When Storage is Allocated 

There are two methods of allocating storage for variables: automatic and 
static. For an automatic variable, storage is allocated when the block 
containing the variable’s declaration begins execution. Storage is released 
when execution of the block ends. If the block is entered again, storage is 
allocated again, and so on. When storage is released, the value of the 
variable is lost. 

For a static variable, storage is allocated (and initialized, if that parameter is 
included) only once, at load time. Storage remains allocated throughout 
execution of the module. However, even though storage remains allocated, a 
static variable still follows normal scope rules. It can be accessed only within 
the block in which it is declared. A reference to a static variable from an 
outer block is an error even though storage for the static variable is still 
allocated. 

The ability to declare a static variable is important, for example, in the case 
where an XDCL variable is referenced by a procedure before the procedure 
that declares the variable is executed. Because an XDCL variable is static 
(refer to Scope earlier in this chapter for further information), it is allocated 
space and is initialized immediately at load time; therefore, it is available to 
be referenced before execution of the procedure that actually declares it as 
XDCL. 

A variable can be declared static explicitly with the STATIC attribute. It is 
assumed to be static implicitly if it is in the outermost level of a module or if 
it has any other attributes declared. In all other cases, CYBIL assumes the 
variable is automatic. Only a static variable can be initialized. 
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The period between the time storage for a variable is allocated and the time 
that storage is released is called the lifetime of the variable. It is defined in 
terms of modules and blocks. The lifetime of an automatic variable is the 
execution of the block in which it is declared. The lifetime of a static variable 
is the execution of the entire module. An attempt to reference a variable 
beyond its lifetime causes an error and unpredictable results. 

The lifetime of a formal parameter in a procedure is the lifetime of the 
procedure in which it is a part. Storage space for the parameter is allocated 
when the procedure is called and released when the procedure finishes 
executing. 

The lifetime of a pointer must be less than or equal to the lifetime of the data 
to which it is pointing. 

The lifetime of a variable that is allocated using the storage management 
statements (described in chapter 5) is the time between the allocation of 
storage and the release of storage. A variable allocated by an automatic 
pointer (using the ALLOCATE statement) must be explicitly freed (using the 
FREE statement) before the block is left, or the space will not be released by 
the program. When the block is left, the pointer no longer exists and, 
therefore, the variable cannot be referenced. If the block is entered again, the 
previous pointer and the variable referenced by the pointer cannot be 
reclaimed. 

Example: 

In this example, the variables COUNTER and FLAG will exist during 
execution of the entire module; however, they can be accessed only within 
program MAIN. 

PROGRAM main; 

VAR 

counter: [STATIC] integer := 0, 
flag: [STATIC] boolean; 

PROCEND main; 
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Where Storage is Allocated 

You can optionally specify that storage for a variable be allocated in a 
particular section. A section is a storage area that can hold variables sharing 
common access attributes, such as read-only variables or read/write 
variables. You can define the section and its access attributes yourself using 
the section declaration (discussed later in this chapter). 

If you define a section with the section READ attribute, you define a read¬ 
only section in the hardware.f Any variable declared with that section’s 
name as an attribute will reside in that read-only section. When you specify 
the name of a read-only section in a variable declaration, you must also 
include the variable access attribute READ. 


In addition to any sections you define, CYBIL has several predefined 
sections. You cannot assign a variable to one of these sections explicitly, in 
the sense that you could include the section name as an attribute in your 
variable declarations. Instead, the variable is assigned to one of these 
predefined sections implicitly, based on its other attributes and 
characteristics. For example, all static variables that are not assigned to a 
user-defined section are automatically assigned to a section named 
$STATIC. The following are the CYBIL section names and their contents. 


Section _ Description _ 

$BINDING The binding section that contains the links to 

external procedures and the data of the module. 

CYB$DEFAULT_ HEAP The CYBIL default heap. 

$LITERAL Constants. 

$PARAMETER A subset of the SSTACK section that contains 

parameter list variables. 


$REGISTER 

$STACK 

$STATIC 


Variables that exist only in hardware registers. 
Automatic variables. 

Static variables that are not already assigned to 
a user-defined section. 


t A read-only section is a hardware feature. Data that resides in a physical 
area of the machine designated as a read-only section is protected by 
hardware, not by software. This feature is described in further detail in 
volume II of the virtual state hardware reference manual. 
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The SCL Object Code Management manual gives further information on 
sections regarding the object module format expected as input by the loader 
and the object library generator. 

Example-' 

This example defines a read-only section named NUMBERS. The variable 
INPUTNUMBER is a read-only variable that also resides in the section 
NUMBERS. In the variable declaration, the READ attribute causes the 
compiler to check that the variable is not written; the read-only section name, 
NUMBERS, causes the hardware to ensure that the variable is not written. 

SECTION 

numbers: READ; 

VAR 

input_number: [READ, numbers] integer := 100; 
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Initialization 

You can assign an initial value to a variable only if it is a static variable. 

The value can be a constant expression, an indefinite value constructor 
(described next), or a pointer to a global procedure. The value must be of the 
proper type and in the proper range. If you don’t specify an initial value, the 
value of the variable is undefined. 

An indefinite value constructor is essentially a list of values. It is used to 
assign values to the structured types sets, arrays, and records. It allows you 
to specify several values rather than just one. Values listed in a value 
constructor are assigned in order (except for sets, which have no order). The 
types of the values must match the types of the components in the structure 
to which they are being assigned. An indefinite value constructor has the 
form 

[value {, value}...] 

where value can be one of the following: 

• A constant expression. 

• Another value constructor (that is, another list). 

• The phrase 

REP number OF value 

which indicates the specified value is repeated the specified number of 
times. 

• The asterisk character (*), which indicates the element in the 
corresponding position is uninitialized. 

The REP phrase can be used only in arrays. The asterisk can be used only in 
arrays and records. For further information, refer to the descriptions of 
arrays and records in chapter 4. 

If you assign an initial value to a string variable and the variable is longer 
than the initial value, spaces are added on the right of the initial value to fill 
the field. If the initial value is longer than the variable, the initial value is 
truncated on the right to fit the variable. 

In a variant record, fields are initialized in order until a special variable 
called the tag field name is initialized. The tag field name is then used to 
determine the variant for the remaining field or fields in the record, and they 
are likewise initialized in order. 

Depending on the attributes defined in the variable declaration, initialization 
is required, prohibited, or optional. Table 3-1 shows the initialization possible 
for various attributes. 
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Table 3-1. Attributes and Initialization 


Attributes Specifiedf 

Initialization 

None 

Optional if static variable; prohibited 
if automatic variable. 

READ 

Required. 

READ,STATIC 

Required. 

READ,XDCL 

Required. 

READ,STATIC,XDCL 

Required. 

READ,section_name 

Required. 

READ,XDCL,section_name 

Required. 

XREF 

Prohibited. 

XREF,READ 

Prohibited. 

XREF,STATIC 

Prohibited. 

XREF,RE AD,STATIC 

Prohibited. 

STATIC 

Optional. 

XDCL 

Optional. 

XDCL,STATIC 

Optional. 

section name 

Optional. 

section _name,XDCL 

Optional. 

t The static attribute is assumed if any attributes are specified. 
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Example: 

The variables declared in this example are inside program MAIN. Therefore, 
they are automatic unless declared with an attribute. TOTAL is automatic 
and as such cannot be initialized. COUNT is declared static and can be 
initialized. ALPHA and BETA are also static and can be initialized because 
they have other attributes declared. 

PROGRAM main; 

VAR 

total: integer, 

count: [STATIC] integer := 0, 

alpha, 

beta: CXDCL, READ] char := 'p'; 

PROCEND main; 
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Type Declaration 

The standard data types that are defined in CYBIL are described in chapter 
4. Any of these can be declared as a valid type within a variable declaration. 
The type declaration allows you to define a new data type and give it a 
name, or redefine an existing type with a new name. Then that name can be 
used as a valid type within a variable declaration. 

Use this format for a type declaration: 

TYPE name = type {,name = type}...; 

name 

Name to be given to the new type, 
type 

Any of the standard types defined by CYBIL or another user-defined 
type. 

Once you define a type, you can use it to define yet another type. Thus, you 
can build a very complex type that can be referred to by a single name. 

The type declaration is evaluated at compilation time. It does not occupy 
storage space during execution. 

Examples: 

In this example, INT is defined as a type consisting of all the integers; it is 
just a shortened name for a standard type. LETTERS is defined as a type 
consisting of the characters ’a’ through ’z’ only; this is a selective subset of 
the standard type characters. DEVICES is an ordinal type that in turn is 
used to define EQ_TABLE, a type consisting of an array of 10 elements. Any 
element in the type EQ TABLE can have one of the ordinal values specified 
in DEVICES. 

TYPE 

int = integer. 

Letters = 'a' .. 'z', 

devices = (lp512, dk844, dk885, nt679), 

eq_table = array Cl .. 10] of devices; 

VAR 

i: int, 

alpha: Letters, 
table_1: eq_table, 

status_table: array Cl ..3] of eq_table; 
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All of the variables in the preceding example could have been declared using 
variable declarations only, as in: 

VAR 

i: integer, 
alpha: 'a' .. 1 z', 

table_1: array Cl .. 10] of (lp512, dk844, dk885, nt679), 
status_table: array Cl .. 3] of array Cl .. 10] of 
(lp512, dk844, dk885, nt679); 

However, it becomes cumbersome to declare a complex structure using only 
standard types. Defining your own types lets you avoid needless repetition 
and the increased possibility of errors. In addition, it makes code easier to 
maintain; to add a new device in the first example, you need add it only in 
the type declaration, not in every variable declaration that contains devices. 
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Section Declaration 

A section is an optional working storage area that contains variables with 
common access attributes. You can define a section and its associated 
attributes with the section declaration. Including the section name in a 
variable declaration causes the variable to reside in that section. 

Use this format for a section declaration: 

SECTION name {,name}... ■ attribute 
(.name {,name}... '■ attribute}...-, 

name 

Name of the section, 
attribute 

The keyword READ or WRITE. 

A section defined with the READ attribute is considered a read-only section.f 
A variable declared with that section’s name will reside in read-only 
memory. In this case, the variable access attribute READ must also be 
included in the variable declaration. The section name causes hardware 
protection; the READ attribute causes compiler checking. 

A section defined with the WRITE attribute contains variables that can be 
both read and written. 

The initialization of variables declared with a section name depends on their 
attributes, as shown in table 3-1. Variables declared with a section name are 
static. 

The names and contents of predefined CYBIL sections are given earlier in 
this section under Where Storage is Allocated. The SCL Object Code 
Management manual gives further information on sections regarding the 
object module format expected as input by the loader and the object library 
generator. 


t A read-only section is a hardware feature. Data that resides in a physical 
area of the machine designated as a read-only section is protected by 
hardware, not by software. This feature is described in further detail in 
volume II of the virtual state hardware reference manual. 


3-18 CYBIL Language Definition 


Revision 1 



SECTION DECLARATION 


Example: 

Two sections are defined in this example: LETTERS is a read-only section 
and NUMBERS is a read/write section. The variable CONTROL_LETTER 
is a read-only variable that resides in LETTERS. The READ attribute is 
required because of the read-only section name. UPDATE _ NUMBER is a 
variable that can be read or written, and resides in the section NUMBERS. 
In this example, it is also declared as an XDCL variable but this is not 
required. 

SECTION 

Letters: READ, 
numbers: WRITE; 

VAR 

control_letter: [READ, Letters] char := 'p 1 , 
update_number: [XDCL, numbers] integer; 
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Types 


4 


There are many standard types defined within CYBIL. A variable can be 
assigned to (that is, be made an element of) any of these types. The type 
defines characteristics of the variable and what operations can be performed 
using the variable. In general, operations involving nonequivalent types are 
not allowed; one type cannot be used where another type is expected. 
Exceptions are noted in the descriptions of types that follow. 

In this chapter, types are grouped into three major categories: basic types, 
structured types, and storage types. 

Basic types are the most elementary. They can stand alone but are also used 
to build the more complex structures. The basic types are: 

• Scalar types (integer, character, boolean, ordinal, and subrange) 

• Floating-point types (real) 

• Cell types 

• Pointer types 

Structured types are made from combinations of the basic types. The 
structured types are: 

• Strings 

• Arrays 

• Records 

• Sets 

Storage types hold groups of components of various types. The storage types 
are: 


• Heaps 

• Sequences 

Most types, when they are declared, have a fixed size. Strings, arrays, 
records, sequences, and heaps can also be declared with an adaptable size 
that is not fixed until execution. For this reason, they are sometimes called 
adaptable types. Adaptable strings, arrays, records, sequences, and heaps 
are discussed at the end of this chapter. 
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Using Types 

Types are used as parameters in two kinds of declarations: the variable 
declaration (to associate a type with a variable name) and the type 
declaration (to associate a type with a new type name). Both declarations are 
described in detail in chapter 3, but their basic formats are: 

VAR name : { [attributes ]} type {■'= initial_ualue }; 

TYPE name = type; 

The description of each type shown in this chapter includes the keyword and 
any additional information necessary to specify that type as a parameter. 
The keywords replace the generic word type in the variable and type 
declarations. For example, you would use the keyword INTEGER to specify 
an integer type. The variable declaration would be: 

VAR name : { [attributes ]) INTEGER {•'= initial_value }; 

The type declaration would be: 

TYPE name = INTEGER; 


Equivalent Types 

As mentioned earlier in this chapter, operations involving nonequivalent 
types are not allowed. Two types can be equivalent, though, even if they 
don’t appear to be identical. For example, two arrays can have different 
expressions defining their sizes, but the expressions may yield the same 
value. Rules for determining whether types are equivalent are given in the 
following descriptions of the types. 

Adaptable types and bound variant record types (described under Records 
later in this chapter) actually define classes of related types that vary by a 
characteristic, such as size. Adaptable type variables, bound variant record 
type variables, and pointers to both types are fixed explicitly at execution 
time. These types are said to be potentially equivalent to any of the types to 
which they can adapt. That is, during compilation, references to adaptable 
types and bound variant record types are allowed wherever there is a 
reference to one of the types to which they can adapt. However, further type 
checking is done during execution when each type is fixed (assigned to a 
specific type). It is the current type of an adaptable or bound variant record 
type that determines what operations are valid for it at any given time. 
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Basic Types 

Scalar Types 

All scalar types have an order; that is, for every element of a scalar type you 
can find its predecessor and successor. 

Scalar types are made up of five types: 

• Integer 

• Character 

• Boolean 

• Ordinal 

• Subrange 
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Integer 

Use the keyword INTEGER to specify an integer type. 

Integers range in value from -(2 63 -l) to 2 63 -l; that is, 

-7FFFFFFFFFFFFFFF hexadecimal through 7FFFFFFFFFFFFFFF 
hexadecimal. In general, the subrange type should be used rather than the 
integer type. This allows the compiler to perform more rigorous type¬ 
checking and may reduce the amount of storage needed to hold the value. 

The operations permitted on integers are assignment, addition, subtraction, 
multiplication, division (both quotient and remainder), all relational 
operations, and set membership. Refer to Operators in chapter 5 for further 
information on operations. 

The functions $INTEGER and $REAL, described in chapter 6, convert 
between integer type and real type. The $CHAR function, also described in 
chapter 6, converts an integer value from 0 to 255 to a character according to 
its position in the ASCII collating sequence. 

Example: 

This example shows the definition of a new type named INT, which consists 
of elements of the type integer. The variable declaration declares variable I to 
be of type INT, which is the integer type just declared. Also declared as a 
variable is NUMBERS, which is explicitly of integer type. Because 
NUMBERS is static, it can be initialized. 

TYPE 

int = integer; 

VAR 

i: int, 

numbers: [STATIC] integer := 100; 
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Character 

Use the keyword CHAR to specify a character type. 

An element of the character type can be any of the characters in the ASCII 
character set included in appendix B. It is always a single character; more 
than one character is considered a string. (A string is one of the structured 
types discussed later in this chapter. A string of length 1 can sometimes be 
used as a character. Refer to Substrings later in this chapter.) 

The operations permitted on characters are assignment, all relational 
operations, and set membership. A character can be assigned to and 
compared to a string of length 1. Refer to Operators in chapter 5 for further 
information on operations and to Strings later in this chapter for further 
information on string assignment. 

The IINTEGER function described in chapter 6 converts a character value to 
an integer value based on its position in the ASCII collating sequence. The 
$CHAR function, also described in chapter 6, converts an integer value 
between 0 and 255 to a character in the ASCII collating sequence. 

Example: 

This example shows the definition of a new type named LETTERS, which 
consists of elements of the type character. The variable declaration declares 
variable ALPHA to be of type LETTERS, which is type character; it is static 
and initialized to the character ’j’. The variable IDS is explicitly declared to 
be of type character. 

TYPE 

Letters = char; 

VAR 

alpha: [STATIC] Letters := ’j', 
ids: char; 
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Boolean 

Use the keyword BOOLEAN to specify a boolean type. 

An element of the boolean type can have one of two values: FALSE or 
TRUE. As with other scalar types, boolean values are ordered. Their order is 
FALSE, TRUE. FALSE is always less than TRUE. 

You get a boolean value by performing a relational operation on two objects 
of the same type. You can perform some, but not necessarily all, relational 
operations on every type except the following: 

• Arrays or structures that contain an array as a component or field 

• Variant records 

• Sequences 

• Heaps 

• Records that contain a field of one of the preceding types 

The operations permitted on boolean values are assignment, all relational 
operations, set membership, and boolean sum, product, difference, exclusive 
OR, and negation. Refer to Operators in chapter 5 for further information on 
operations. 

The $INTEGER function described in chapter 6 converts a boolean value to 
an integer value. 0 is returned for FALSE; 1 is returned for TRUE. 

Example: 

This example shows the definition of a new type named STATUS, which 
consists of the boolean values FALSE and TRUE. The variable declaration 
declares variable CONTINUE to be of type STATUS; that is, it can be either 
FALSE or TRUE. The variable DEBUG is explicitly declared to be boolean 
and, because it is a read-only variable and therefore static, it can be 
initialized. 

TYPE 

status = boolean; 

VAR 

continue: status, 

debug: [READ] boolean := TRUE; 
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Ordinal 

The ordinal type differs from the other scalar types in that you, the user, 
define the elements within the type and their order. The term ordinal refers 
to the list of elements you define; the term ordinal name refers to an 
individual element within the ordinal. 

Use this format to specify an ordinal: 

(name, name {,name...}) 

name 

Name of an element within the ordinal. There must be at least two 
ordinal names. 

The order is given in ascending order from left to right. 

Each ordinal name can be used in just one ordinal type. If you use a name in 
more than one ordinal, a compilation error occurs. 

Ordinals are used to improve the readability and maintainability of 
programs. They allow you to use meaningful names within a program rather 
than, for example, map the names to a set of integers that are then used in 
the program to represent the names. 

The operations permitted on ordinals are assignment, all relational 
operations, and set membership. 

Two ordinal types are equivalent if they are defined in terms of the same 
ordinal type names. 

The $INTEGER function described in chapter 6 converts an ordinal value 
(that is, a name) to an integer value based on its position within the defined 
ordinal. The first ordinal name has an integer value of 0, the second name an 
integer value of 1, and so on. 
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Examples: 

In this example, the type declaration defines a type named COLORS, which 
is an ordinal that consists of the elements RED, GREEN, and BLUE. The 
variable PRIMARY_ COLORS is of COLORS type and therefore has the 
same elements. The variable WORK_DAYS explicitly declares the ordinal 
consisting of elements MONDAY through FRIDAY. 

TYPE 

colors = (red, green, blue); 

VAR 

primary_colors: colors, 

work_days: (monday, tuesday, Wednesday, thursday, 
friday); 

In the ordinal type COLORS, the following relationships hold: 

RED < GREEN 
RED < BLUE 
GREEN < BLUE 

You can find the predecessor and successor of every element of an ordinal. 
You can also map each element onto an integer using the $INTEGER 
function (described in chapter 6). For example, $INTEGER(RED) = 0; this is 
the first element of the ordinal. 

The type declaration 

TYPE 

primary_colors = (red, green, blue), 
hot_colors = (red, orange, yellow); 

is in error because the name RED appears in two ordinal definitions. 
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Subrange 

A subrange is not really a new type but a specified range of values within an 
existing scalar type. A variable defined by a subrange can take on only the 
values between and including the specified lower and upper bounds. 

Use this format to specify a subrange: 

lowerbound.. upperbound 
lowerbound 

Scalar expression specifying the lower bound of the subrange. 

upperbound 

Scalar expression specifying the upper bound of the subrange. 

The lower bound must be less than or equal to the upper bound. Both bounds 
must be of the same scalar type. 

The type of a subrange is the type of its lower and upper bounds. If a 
subrange completely encompasses its own type, it is said to be an improper 
subrange type. For example, the subrange 

FALSE..TRUE 

is of type boolean and also contains every element of type boolean. It is 
equivalent to specifying the type itself. An improper subrange type is always 
equivalent to its own type. 

Two subranges are equivalent if they have the same lower and upper bounds. 

Subranges allow for additional error checking. Compilation options are 
available that cause the compiler to check assignments during program 
execution and issue an error if it finds a variable not within range. (Range 
checking is available as an option on the compiler call command and as a 
compiler directive. They are both described in chapter 8.) In addition, 
subranges improve readability. Because a subrange defines the valid range 
of values for a variable, it is more meaningful to the user for documentation 
and maintenance. 

The operations permitted on a subrange are the same as those permitted on 
its type (the type of its lower and upper bound). 
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Example: 

This example shows the definition of a new type named LETTERS, which 
consists of the characters ’a’ through ’z’ only. It also defines an ordinal 
named COLORS consisting of the colors listed. The variable declaration 
declares variable SCORES to consist of the numbers 0 through 100. The 
lower and upper hounds are of integer type, so the subrange is also an 
integer type. STATUS is a subrange of boolean values, which could have 
been declared simply as BOOLEAN. HOT_COLORS is a subrange of the 
ordinal type COLORS. It consists of the colors RED, ORANGE, and 
YELLOW. 

TYPE 

Letters = 'a' .. 'z 1 , 

colors = (red, orange, yellow, white, green, blue); 

VAR 

scores: 0 .. 100, 
status: FALSE .. TRUE, 
hot_colors: red .. yellow; 
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Floating-Point Type 

The floating-point type defines real numbers. 

Real 

Use the keyword REAL to specify a real type. 

Real numbers range in value from 4.8*10~ 1234 to 5.2*10 1232 . 

The operations permitted on real types are assignment, addition, subtraction, 
multiplication, division, and all relational operations. 

The functions $INTEGER and $REAL, described in chapter 6, convert 
between integer type and real type. 
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Cell Type 

The cell type represents the smallest storage location that is directly 
addressable by a pointer. On NOS/VE, a cell is an 8-bit byte within a 64-bit 
memory word. 

Use the keyword CELL to specify a cell type. 

Operations permitted on a cell type are assignment and comparison for 
equality and inequality. 
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Pointer Types 

A pointer represents the location of a value rather than the value itself. 
When you reference a pointer, you indirectly reference the object to which it 
is pointing. 

Use this format to specify a pointer type: 

' type 
type 

Type to which the pointer can point. It can be any defined type. With 
the exception of a pointer to cell type (discussed later in this chapter), 
the pointer can point only to objects of the type specified. 

For example, 

VAR 

integer_pointer: "integer; 

defines a pointer named INTEGER_POINTER that can point only to 
integers. 


INTEGER POINTER 



any 


integer 


Use this format to specify the object of a pointer (that is, what the pointer 
points to): 

pointer _ name " 

pointer _ name 

The name you gave the pointer in the variable declaration. 

This preceding notation is called a pointer reference: it refers to the object to 
which pointer_name points. It can also be referred to as a dereference. For 
example, 

int ege r_pointer" 

identifies a location in memory; it is the location to which INTEGER_ 
POINTER points. 


INTEGER POINTER 


INTEGER POINTER " 



any 


integer 
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You can initialize or assign a value to the object of a pointer as you would 
any other variable; that is: 

pointer_name " := value; 

This assigns the specified value to the object that the pointer points to. For 
example, 

integer_pointer“ := 5; 

assigns the integer value 5 to the location INTEGER_ POINTER points to: 


INTEGER POINTER 


INTEGER POINTER * 



You can assign the object of a pointer to a variable in the same way: 
variable := pointer_name 

This takes the value of what pointer_name points to and assigns it to the 
variable. For example, 

i := integer_pointer"; 

assigns to I the contents of what INTEGER_POINTER points to, that is, 5. 

If a pointer reference is to another pointer type variable, meaning that the 
pointer points to a pointer that in turn points to a variable, you can specify 
the variable in the format: 

pointer_name ““ 

For example, the declarations 

TYPE 

integer_pointer = "integer; 

VAR 

pointer_2: “integer_pointer; 
can be pictured conceptually as follows: 

POINTER_2 POINTER_2"" 

POINTER 2 -► 


a pointer 


any 

INTEGER_PO INTER 


integer 
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POINTER_2 points to a pointer of type INTEGER_POINTER. INTEGER_ 
POINTER points to integers. A reference to POINTER_2 " refers to the 
location of the pointer that in turn points to an integer. A reference to 
POINTER_2 "" refers to the location of the integer. 

The value assigned to a pointer can be: 

• The pointer constant NIL. 

• The pointer symbol “ followed by a variable of the type to which the 
pointer can point. 

• A pointer variable. 

• A pointer-valued function. 

NIL is the value of a pointer variable without an object; the variable is not 
currently assigned to any location. It can be assigned to or compared with 
any pointer of any type. 

Pointers allow you to manipulate storage dynamically. Using pointers, you 
can create and destroy variables while a program is executing. Memory is 
allocated when the variable is created and released when it is destroyed. 
Pointers also allow you to reference the variables without giving each a 
unique name. 

A pointer variable can be a component of a structured type as well as a valid 
parameter in a function. A function can return a pointer variable as a value. 

Permissible operations on pointers are assignment and comparison for 
equality and inequality. 

Pointers to adaptable types (adaptable strings, arrays, records, sequences, 
and heaps) provide the only method for accessing objects of these types other 
than through formal parameters of a procedure. In particular, pointers to 
adaptable types and pointers to bound variant records are used to access 
adaptable variables and bound variant records whose types have been fixed 
by an ALLOCATE, PUSH, or NEXT statement (described in chapter 5). 

Pointers are equivalent if they are defined in terms of equivalent types. A 
pointer to a fixed type (as opposed to an adaptable type) can be assigned and 
compared to a pointer to an adaptable type or bound variant record if the 
adaptable type is potentially equivalent to the fixed type. (Refer to 
Equivalent Types earlier in this chapter for further information on 
potentially equivalent types.) 
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Example: 

The following example shows the declaration and manipulation of two 
pointer type variables. Comments appear to the right. 


TYPE 

ptr = “integer; PTR is a type that can contain pointers to 

integers. 

VAR 

i/ 

j/ 

k: integer, 

pi: ptr, PI is a variable that can contain pointers to 

integers. 

p2: “pi, P2 is a variable that can contain pointers to 

PI (that is, pointers that point to pointers to 
integers). It could have been written as 
P2: " INTEGER. 

bl, 

b2: boolean; 


ALLOCATE pi; 


ALLOCATE p2; 

Pl“ := 10; 
p2“ := pi; 

j := pi"; 

k := p2““; 


bl := j = k; 
b2 := pi" = P 2““; 


pi := NIL; 
k := pi“; 

IF p2 = NIL THEN 
k := k + 1; 

IFEND; 

pi := “(i + j + 2 * k); 


Allocates space for an integer (because that is 
what PI points to) and sets Pi to point to that 
space. 

Allocates space for a pointer that points to an 
integer and sets P2 to point to that pointer. 
The space pointed to by Pi is set to 10. 

The space pointed to by P2 is set to the value 
of the pointer PI. 

The integer variable J is set to what PI points 
to: the integer 10. 

The integer variable K is set to the object of 
the pointer that P2 points to. (Think of P2 "" 
as ”P2 points to a pointer; that pointer points 
to an object.” You are assigning that object to 
K.) P2 points to PI, which points to the 
integer 10. 

J and K are both 10. Bl is TRUE. 

PI points to an integer. P2 points to the 
pointer (PI) that points to the same integer. 
Their values are the same and B2 is TRUE. 

PI no longer points to anything. 

The statement is in error because PI does not 
point to anything. 

A valid statement. K is not incremented 
because P2 still points to PI. 

An invalid statement. The location of an 
expression cannot be found. 
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Pointer to Cell 

A pointer to cell type can take on values of any type. 

Use this format to declare a pointer to a cell: 

'CELL 

A variable declared simply as a pointer type variable can take on as values 
only pointers to a single type, which is specified in the pointer’s declaration. 
A variable declared as a pointer to cell variable has no such restrictions. It 
can take on values of any type. Also, any fixed or bound variant pointer 
variable can assume a value of pointer to cell. 

Permissible operations on a pointer to a cell are assignment and comparison 
for equality and inequality. In addition, a pointer to a cell can be assigned to 
any pointer to a fixed or bound variant type. But the pointer to the fixed or 
bound variant type cannot have as its value a pointer to a variable that is 
not a cell type or, furthermore, whose type is not equivalent to the type to 
which the target of the assignment points. A pointer to a cell can be the 
target of assignment of any pointer to a fixed or bound variant type. 
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Relative Pointer 

Relative pointer types represent relative locations of components within an 
object with respect to the beginning of the object. 

Use this format to specify a relative pointer: 

REL { (parent_name) } "'component_type 

parent _name 

Name of the variable that contains the components being designated 
by relative pointers. Specify a string, array, record, heap, or sequence 
type (either fixed or adaptable). If omitted, the default heap is used. 

component, type 

Type of the component to which the relative pointer will point. 

Relative pointers are generated using the standard function #REL (described 
in chapter 6). A relative pointer cannot be used to access data directly. 
Instead, the relative pointer must be converted to a direct pointer using the 
standard function #PTR (also described in chapter 6). The direct pointer can 
then be used to access the data. 

Relative pointers have three major differences from the other pointers 
discussed in this chapter: 

• Relative pointers may need less space than other pointers. 

• A linked list or array of relative pointers (or some similar organization) 
within a parent type variable is still correct if the entire variable is 
assigned to another variable of the same parent type. 

• Relative pointers cure independent of the base address of the parent type 
variable. 

Operations permitted on a relative pointer are assignment, comparison for 
equality and inequality, and the #PTR function. Relative pointers can be 
assigned and compared if they are of equivalent relative pointer types. 
Relative pointer types are equivalent if they are defined in terms of 
equivalent parent types and equivalent component types. 
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Structured Types 

Structured types are combinations of the basic types already described in 
this chapter (integer, character, boolean, ordinal, subrange, real, cell, and 
pointer). Even the structured types discussed here can be combined with each 
other but they are still essentially groups of the basic types. The structured 
types described in this section are: 

• Strings 

• Arrays 

• Records 

• Sets 


Strings 

A string is one or more characters that can be identified and referenced as a 
whole by one name. 

Use this format to specify a string type: 

STRING (length) 
length 

A positive integer constant expression from 1 to 65,535. 

If you specify an initial value in the variable declaration for a string, it can 
be: 

• A string constant. 

• The name of a string constant declared with a constant declaration. 

• A constant expression (as described in chapter 2). 

A string cannot be packed. Two string types are equivalent if they have the 
same length. 

The operations permitted on string types are assignment and comparison (all 
six relational operations). For further information, refer to Assigning and 
Comparing String Elements later in this chapter. 
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Substrings 

You can reference a part of a string (this is called a substring) or a single 
character of a string. 

Use this format to reference a substring or single character: 
name (position {, length}) 
name 

Name of the string, 
position 

Position within the string of the first character of the substring. (The 
position of the first character of the string is always 1.) Specify a 
positive integer expression less than or equal to the length of the string 
plus one; that is, 

1 < position < string length + 1 

If you specify string length plus one, the substring is an empty string. 
length 

Number of characters in the substring. Specify a nonnegative integer 
expression or * (the asterisk character). If you specify *, the substring 
consists of the character specified by the position parameter and all 
characters following it in the string. If you specify 0, the substring is 
an empty string. Omission causes 1 to be used. 
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A substring reference in the form 
name(position) 

is a substring of length 1, a single character. In this form, it can be used 

anywhere a character expression is allowed. It can be: 

• Compared with a character. 

• Tested for membership in a set of characters. 

• Used as the initial and/or final value in a FOR statement that is 
controlled by a character variable. 

• Used as a value in a CASE statement. 

• Used as an argument in the standard functions $INTEGER, SUCC, and 
PRED. 

• Assigned to a character variable. 

• Used as an actual parameter to a formal parameter of type character. 

• Used as an index value corresponding to a character type index in an 
array. 

A string constant, even if it is declared with a name in a constant (CONST) 

declaration, is not a variable. Therefore, substrings cannot be referenced in a 

string constant. 


Revision D 


Types 


4-21 






STRINGS 


Examples: 

If a string variable LETTERS is declared and initialized as follows 

VAR 

Letters: [STATIC] string (6) := 'abcdef'; 
the following substring references are valid: 


Substring 


Comments 


LETTERS(l) Refers to ’a'. 

LETTERS(6) Refers to *F. 

LETTERS(1,6) Refers to the entire string. 

LETTERS(1,*) Refers to the entire string. 

LETTERS(2,5) Refers to ’bcdef. 

LETTERS(2,*) Refers to ’bcdef. 

LETTERS(2,0) Refers to an empty string 

LETTERS(7,*) Refers to an empty string ”. 

LETTERS(O), LETTERS(8), and LETTERS(8,0) are illegal. 
If a pointer variable is declared and initialized as follows 


VAR 

string_ptr: [STATIC] "string (6) := "Letters; 

then STRING_PTR points to the string LETTERS and the pointer variable 
STRING_PTR" can be used to make substring references just like the 
variable LETTERS. 


Substring _ 

STRING_PTR“(1) 
STRING_ PTR" (6) 
STRING_PTR"(1,6) 
STRING_PTR"(2,*) 
STRING_PTR~(2,0) 


Comments _ 

Refers to ’a’. 

Refers to ’f. 

Refers to the entire string. 
Refers to ’bcdef. 

Refers to an empty string ”. 
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Assigning and Comparing String Elements 

You can assign or compare a character, substring, or string to a substring, 
string variable, or character variable. A character is treated as a string of 
length 1. 

If you assign a value that is longer than the substring or variable to which it 
is being assigned, the value is truncated on the right. If you assign a value 
that is shorter, spaces are added on the right to fill the field. This method is 
also used for comparing strings of different lengths. 

If you assign a substring to a substring of the same variable, the fields 
cannot overlap or the results are undefined. 

The concatenation operation, CAT, cannot be used with string variables. 
Example: 

Assume the string variable DAY is declared and initialized as follows: 

VAR 

day: [STATIC] string (6) := 'monday'; 

The following assignments can be made: 

short := day (1, 3); 
empty := day (1, 0); 

SHORT is assigned the string ’mon’. EMPTY is assigned a null string. 
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Arrays 

An array in CYBIL is a collection of data of the same type. You can access 
an array as a whole, using a single name, or you can access its elements 
individually. 

Use this format to specify an array type: 

[PACKED] ARRAY [subscript_bounds] OF type 
PACKED 

Optional packing parameter. When specified, the elements of the array 
are mapped in storage in a manner that conserves storage space, 
possibly at the expense of access time. If omitted, the array is 
unpacked; that is, the elements are mapped in storage to optimize 
access time rather than to conserve space. (The array itself is always 
mapped into an addressable memory location; that is, it starts on a 
word boundary or, in the case of a packed array in a record, on a byte 
boundary.) For further information on how data is stored in memory, 
refer to appendix D, Data Representation in Memory. 

If the array contains structured types (such as records), the elements of 
that type (the fields in the records) are not automatically packed. The 
structured type itself must be declared packed. 

subscript _ bounds 

Value that specifies the size of the array and what values you can use 
to refer to individual elements. The bounds can be any scalar type or 
subrange of a scalar type; the bounds is often a subrange of integers. 

type 

Type of the elements within the array. The type can be any defined 
type, including another array, except an adaptable type (that is, an 
adaptable string, array, or record). All elements must be of the same 
type. 

Elements of a packed array cannot be passed as reference (that is, VAR) 
parameters in programs, functions, or procedures. 

Two array types are equivalent if they have the same packing attribute, 
equivalent subscript bounds, and equivalent component types. 

The only operation permitted on an array type is assignment. 
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Initializing Elements 

An array can be initialized using an indefinite value constructor. An 
indefinite value constuctor is a list of values assigned in order to the 
elements of an array. The first value in the list is assigned to the first 
element, and so on. The number of values in the value constructor must be 
the same as the number of elements in the array. The type of the values must 
match the type of the elements in the array. An indefinite value constructor 
has the form 

[value {,value}...] 

where value can be one of the following: 

• A constant expression. 

• Another value constructor (that is, another list). 

• The phrase 

REP number OF value 

which indicates the specified value is repeated the specified number of 
times. 

• The asterisk character (*), which indicates the element in the 
corresponding position is uninitialized. 

An indefinite value constructor can be used only for initialization; it cannot 
be used to assign values during program execution. Individual elements can 
be assigned during execution using the assignment statement (described in 
chapter 5). 

Referencing Elements 

The array name alone refers to the entire structure. 

Use this format to refer to an individual element of an array: 

array_name[subscript] 

subscript 

A scalar expression within the range and of the type specified in the 
subscript _ bounds field of the array declaration. This subscript 
specifies a particular element. 
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Examples: 

This example shows the definition of a type named POS_ TABLE, which is 
an array of 10 elements that can take on the values defined in POSITION. 

The variable declaration declares variable NUMBERS to be an array of five 
elements initialized to the values 1, 2, 3, 4, and 5 where 1 is the value of the 
first element, and so on. LETTERS is an array of 26 elements that can be 
any characters. BIG_TABLE is a 100-element array, each element of which 
is an array of 10 elements. 

TYPE 

position = (boi, asis, eoi), 
pos_table = array Cl .. 103 of position; 

VAR 

i: [STATIC] integer := 5, 

numbers: [STATIC] array Cl .. 5] of integer := Cl, 2, 3, A, 51 , 
letters: array C'a' .. 'z'] of char, 
big_table: array Cl .. 100] of pos_table; 

The declaration of BIG_TABLE is equivalent to: 

VAR 

big_table: array [1 .. 100] of array Cl .. 10] of position; 

You can reference individual elements using the following statements: 

numbers Ci ] This reference is the same as 

NUMBERS[5]; it refers to the fifth 
element of the array NUMBERS. 

letters C'b'] := 'B'; This statement sets the second 

element of the array LETTERS to the 
uppercase character B. 

big_table Cl3] CIO] := asis; This statement sets the tenth element 

of the thirteenth array to ASIS. 
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The following example shows the declaration and initialization of a two- 
dimensional array named DATA_TABLE. All of the components of the third 
element of the array (which is an array itself) are set to 0. Notice that the 
third element of the last array, DATA_ TABLE [4][3], is uninitialized. 

TYPE 

innerarray = array Cl ..53 of integer, 
twodim = array Cl ..43 of innerarray; 

VAR 

data_table: CSTATIC3 twodim := CC5, - 10, 2, 6, 33, 

C4, 11, 19, - 3, 63, 

CREP 5 of 03, 

C3, - 9, * , 4, 1533; 
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Records 

Records are collections of data that can be of different types. You can access 
a record as a whole using a single name, or you can access elements 
individually. 

A record has a fixed number of components, usually called fields, each with 
its own unique name. Different fields are used to indicate different data types 
or purposes. 

There are two types of records: invariant records and variant records. 
Invariant records consist of fields that don’t change in size or type. Variant 
records can contain fields that vary depending on the value of a key variable. 
Formats used for specifying both kinds of records are given later in this 
chapter. 

Operations permitted on record types are assignment and, for invariant 
records only, comparison for equality and inequality. The invariant records 
being compared cannot contain arrays as fields. 


Invariant Records 

An invariant record consists of fields that do not vary in size or type once 
they have been declared. They are called fixed or invariant fields. 

Use this format to specify an invariant record: 

{PACKED} RECORD 

field_name : {ALIGNED {[offset MOD base]}} type 
{,field_name ■' {ALIGNED {[offset MOD base]}} type}... 

RECEND 

PACKED 

Optional packing parameter. When specified, the fields of a record are 
mapped in storage in a manner that conserves storage space, possibly 
at the expense of access time. If omitted, the record is unpacked; that 
is, the fields are mapped in storage to optimize access time rather than 
to conserve space. For further information on how data is stored in 
memory, refer to appendix D, Data Representation in Memory. 

If one of the fields is a structured type (such as another record), the 
elements of that type are not packed automatically. The structured type 
itself must be declared packed. 

field_name 

Name identifying a particular field. The name must be unique within 
the record. Outside of the record declaration, it can be redefined. 
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ALIGNED 

Optional alignment parameter. If specified, it can appear alone or with 
an offset, in the form: 

ALIGNED [offset MOD base] 

When a field is aligned, it is mapped in storage so that it is directly 
addressable. This means the field begins on an addressable boundary 
to facilitate rapid access to the field. This may negate some of the effect 
of packing the record. For further information, refer to Alignment later 
in this chapter. 

offset MOD base 

Optional offset to be used in conjunction with the ALIGNED 
parameter. This offset causes the field to be mapped to a particular 
hardware address relative to the specified base and offset. Specify a 
particular word or a particular byte within a word. Base is evaluated 
first to find the word boundary; offset is then evaluated to determine 
the number of bytes offset within that word. Filler is created if 
necessary to ensure that the field begins on the specified word or byte. 

offset 

Byte offset within the word specified by base. Specify an integer 
constant less than base. 

base 

Word boundary. Specify an integer constant that is divisible by 8. 
For automatic variables, the base can only be 8. 

type 

Any defined type, including another record, but not an adaptable type. 

Elements of a packed record cannot be passed as reference (that is, VAR) 
parameters in programs, functions, or procedures unless they are aligned. 

The only operations possible on whole invariant records are assignment and 
comparison. A record can be assigned to another record if they are both of 
the same type. A record can also be compared to another record for equality 
or inequality if they are both of the same type. Invariant record types are the 
same if they have the same packing attributes, the same number of fields, 
and corresponding fields have the same field names, same alignment 
attribute, and equivalent types. 
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Example" 

This example shows the definition of two new types, both records. The record 
named DATE has three fields that can hold, respectively, DAY, MONTH, 
and YEAR. The record named RECEIPTS appears to contain two fields, 
NAME and PAYMENT; but PAYMENT is itself a record consisting of the 
three fields in DATE, just described. Initialization of fields within records is 
discussed under Initializing Elements later in this chapter. 

TYPE 

date = record 
day: 1 .. 31, 
month: string (4), 
year: 1900 .. 2100, 
recend, 

receipts = record 
name: string (40), 
payment: date, 
recend; 


Variant Records 

A variant record contains fields that may vary in size, type, or number 
depending on the value of an optional tag field. These different fields are 
called variant fields or simply variants. 

Use this format to specify a variant record: 

{PACKED} {BOUND} RECORD 

{fixed_field_name •" {ALIGNED {[offset MOD base] J} type}...] 
CASE {tag_field_name •" } tag_field_type OF 
= tag_field_value = 
variant, field 
{= tag _ field _value = 
variant _field}... 

CASEND 

RECEND 


t When you specify more than one fixed field, you must separate them with 
commas. 
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PACKED 

Optional packing parameter. When specified, the fields of a record are 
mapped in storage in a manner that conserves storage space, possibly 
at the expense of access time. If omitted, the record is unpacked; that 
is, the fields are mapped in storage to optimize access time rather than 
to conserve space. For further information on how data is stored in 
memory, refer to appendix D, Data Representation in Memory. 

If a field is a structured type (such as another record), the elements of 
that type are not packed automatically. The structured type itself must 
be declared packed. 

BOUND 

Optional parameter indicating that this is a bound variant record. If 
specified, the tag_field_name parameter is required. Additional 
information on bound variant records follows the parameter 
descriptions. 

fixed _field_name 

The name of a fixed field (one that does not vary in size), as described 
under Invariant Records earlier in this chapter. The name must be 
unique within the record. Outside of the record declaration, it can be 
redefined. There can be zero or more fixed fields. 

ALIGNED 

Optional alignment parameter; the same as that for an invariant 
record. If specified, it can appear alone or with an offset in the form: 

ALIGNED [offset MOD base] 

When a field is aligned, it is mapped in storage so that it is directly 
addressable. This means the field begins on an addressable boundary 
to facilitate rapid access to the field. This may negate some of the effect 
of packing the record. For further information, refer to Alignment later 
in this chapter. 
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offset MOD base 

Optional offset to be used in conjunction with the ALIGNED 
parameter, the same as that for an invariant record. This offset causes 
the field to be mapped to a particular hardware address relative to the 
specified base and offset. Specify a particular word or a particular byte 
within a word. Base is evaluated first to find the word boundary; offset 
is then evaluated to determine the number of bytes offset within that 
word. Filler is created if necessary to ensure that the field begins on the 
specified word or byte. 

offset 

Byte offset within the word specified by base. Specify an integer 
constant less than base. 

base 

Word boundary. Specify an integer constant that is divisible by 8. 
For automatic variables, the base can only be 8. 

type 

Any defined type, including another record, but not an adaptable type. 
tag_field_ name 

Optional parameter specifying the name of the variable that 
determines the variant. The current value of this variable determines 
which of the variant fields that follow will actually be used. If omitted, 
the variant that had the last assignment made to one of its fields is 
used. This parameter is required if the record is a bound variant record 
(BOUND is specified). Additional information is given following the 
parameter descriptions. 

tag _ field _ type 

Any scalar type. This type defines the values that the tag_field_value 
can have. 

tag_field_ value 

A constant scalar expression or subrange. Specify one of the possible 
values that can be assigned to the variable specified by tag _ field _ 
name. It must be of the type and within the range specified by tag_ 
fie Id _ type. Specifying a subrange has the same effect as listing each 
value separately. 

variant_field 

Zero or more fixed fields of the same form as that shown in the second 
line of this format. This field exists only if the current value of tag_ 
field_name is the same as that in the tag_field_value associated with 
the variant_field. The last field can be a variant itself. 
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The variant fields must follow all invariant (fixed) fields in the record. The 
field following the reserved word CASE is called the tag_field_name. The 
tag_field _ name can take on different values during execution. When its 
value matches one of the values specified in a tag_field_value, the variants 
associatd with that tag_field_value are used. Variants themselves consist of 
zero or more fixed fields optionally followed by another variant. If the last 
field is itself a variant, it can have another CASE clause, tag _ field _ name, 
and so on. 

The tag_field_name is an optional field. When it is omitted, no storage is 
assigned for the tag field. If the record has no tag field, you choose a variant 
by making an assignment to a subfield within a variant. The variant 
containing that subfield becomes the currently active variant. In a variant 
record without a tag field, all fields in a new active variant become undefined 
except the subfield that was just assigned. An attempt to access a variant 
field that is not currently active produces undefined results. 

Space for a variant record is allocated using the largest possible variant. 

Variant record types are equivalent if they have the same packing attribute, 
their fixed fields sue equivalent (as defined for invariant record types), they 
have the same tag field names, their tag field types are equivalent, their tag 
field values are the same, and their corresponding variant fields are 
equivalent. 

A bound variant record is specified by including the BOUND parameter; the 
tag_field_name is also required. A bound variant record type can be used 
only to define pointers for bound variant record types (that is, bound variant 
pointers). A variable of this type is always allocated in a sequence or heap, or 
in the run-time stack managed by the system. 

When allocating a bound variant record, you must specify the tag field 
values that select the variation of the record. Only the specified space is 
allocated. The ALLOCATE statement in this case returns a bound variant 
pointer. 

If a formal parameter of a procedure is a variant record type, the actual 
parameter cannot be a bound variant record type. 

A record cannot be assigned to a variable of bound variant record type. 

Bound variant record types are equivalent if they are defined in terms of 
equivalent, unbound records. A bound variant record type is never equivalent 
to a variant record type. 
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Example: 

This example defines a type named SHAPE, which becomes the type of the 
tag field, in this case a variable named S. When S is equal to TRIANGLE, 
the record containing fields SIZE, INCLINATION, ANGLE1, and ANGLE2 
is used as if it were the only record available. When the value of S changes, 
the record variant being used changes too. 

TYPE 

shape = (triangle, rectangle, circle), 
angle = - 180 .. 180, 
figure - record 
X, 

y, 

area: real, 
case s: shape of 
= triangle = 
size: real, 
inclination, 
anglel, 

angle2: angle, 

= rectangle = 
sidel, 

side2: integer, 
skew, 

angle3: angle, 

= circle = 

diameter: integer, 
casend, 
recend; 
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Initializing Elements 

A record can be initialized using an indefinite value constructor. An 
indefinite value constructor is a list of values assigned in order to the fields 
of a record. The first value in the list is assigned to the first field, or first 
element in a field, and so on. The type of the values must match the type of 
the elements in the field. An indefinite value constructor has the form 

[value {, value}...] 

where value can be one of the following: 

• A constant expression. 

• Another value constructor (that is, another list). 

• The asterisk character (*), which indicates the element in the 
corresponding position is uninitialized. 

An indefinite value constructor can be used only for initialization; it cannot 
be used to assign values during program execution. Individual fields can be 
assigned during execution using the assignment statement (described in 
chapter 5). 

Example: 

The variable BIRTH _ DAY, in this example, is a record with the fields 
described in the record type named DATE. It is initialized using an indefinite 
value constructor to the 24th day of August, 1950. 

TYPE 

date = record 
day: 1 .. 31, 
month: string (4), 
year: 1900 .. 2100, 
recend; 

VAR 

birth_day: [STATIC] date := [24, 'aug', 1950]; 
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Referencing Elements 

The record name alone refers to the entire structure. 

Use this format to access a field in a record: 

record_name.field_name {.sub_field_name )... 
record_name 

Name of the record as declared in the variable declaration. 

field_name 

Name of the field to be accessed. If the field is an array, a reference to 
an individual element can also be included using the form: 

field_name[subscript] 

sub _field _name 

Optional field name. Use this parameter if the field previously specified 
is itself a structured type, for example, another record. If the contained 
field is an array, you can include a reference to an individual element 
in the format: 

sub _field_ name[subscript] 

Example: 

The variable PROFILE is a record with the fields described in the record 
type STATS. In this example, PROFILE is initialized with the values in the 
indefinite value constructor in the variable declaration. 

TYPE 

stats = record 
age: 6 .. 66, 
married: boolean, 
date: record 
day: 1 ..31, 
month: 1 .. 12, 
year: 80 .. 90, 
recend, 
recend; 

VAR 

profile: CSTATIC3 stats := C23, FALSE, C3, 5, 8233; 
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The following references can be made to fields: 

profile.age This field contains 23. 

prof i Le.married This field contains FALSE, 

prof i le.date.day This field contains 3. 

prof i Le.date.month This field contains 5. 
prof i Le.date.year This field contains 82. 

Alignment 

Unpacked records and their fields are always aligned (that is, directly 
addressable). Even if it is packed, a record itself is always aligned (that is, 
the first field is directly addressable) unless it is an unaligned field within 
another packed structure. Fields in a packed record, however, are not aligned 
unless the ALIGNED attribute is explicitly included. Aligning the first field 
of a record aligns the entire record. 

Unpacked records and their fields, because they are aligned, can always be 
passed as reference (that is, VAR) parameters in programs, functions, and 
procedures. Packed records must be aligned to be valid as reference 
parameters. Packed, unaligned records cannot be used. 
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Sets 

A set is a collection of elements that, unlike arrays and records, is always 
operated on as a single unit. Individual elements are never referenced. 

Use this format to specify a set type: 

SET OF scalar_type 
scalar _ type 

Type of all the elements that will be within the set. Specify a scalar 
type or a subrange of a scalar type. The maximum number of elements 
that can be in a set is 32,767. 

All members of a set must be of the same type. Members within a set have no 
specific order; that is, order has no effect in any of the operations performed 
on sets. 

Set types are equivalent if their elements have equivalent types. 

Permissible operations on sets are assignment, intersection, union, 
difference, symmetric difference, negation, inclusion, identity, and 
membership. Refer to Operators in chapter 5 for further information on set 
operations. The SUCC and PRED functions are not defined for set types. 

The difference (-) or symmetric difference (XOR) of two identical sets is the 
empty set. The empty set is contained in any set. For a given set, the 
complement of the empty set, -[ ], is the full set. 

Initializing and Assigning Elements 

Values can be assigned to a set using an indefinite value constructor or a set 
value constructor. An indefinite value constructor can be used only for 
initialization; a set value constructor can be used for both initialization and 
assignment during program execution. 

An indefinite value constructor is a list of values assigned to the set. The 
type of the values must match the type of the set. 

Use this format to specify an indefinite value constructor: 

[value {,value}...] 

value 

A constant expression or another indefinite value constructor (that is, 
another list). 
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A set value constructor constructs a set through explicit assignment. Use 
this format to specify a set value constructor: 

$name [ { value {,value}...} ] 

name 

Name of the set type. The dollar sign ($) must precede the name to 
indicate a set value constructor. 

value 

An expression of the same type as that specified for the set. When used 
in initialization, only constants or constant expressions are valid. The 
empty set can be specified by [ ]. 

A set value constructor can be used wherever an expression can be used. 
Example: 

This example shows the declaration of a variable named ODD that is a type 
of a set of integers from 0 to 10. It is initialized with an indefinite value 
constructor assigning the integers 1, 3, and 5 to the set. The variable 
VOWELS is a set that can contain any of the letters ’a’ through ’z’. It is 
assigned the letters ’a’, ’e’, ’i’, ’o’ and ’u’ using a set value constructor. It 
constructs a set of type C, which contains the specified letters; then that set 
is assigned to the set VOWELS. The variables LIST_1 and LIST_2 are sets 
that can contain any characters. LIST_1 is assigned, using a set value 
constructor, the letters ’x’, ’y’, and ’z’. LIST_2 is assigned the complement of 
’x’, ’y’, and ’z’, that is, a set consisting of every character except the letters 
’x’, ’y’, and ’z’. 

TYPE 

a = set of 0 .. 10, 
c = set of 'a' .. 'z', 
ch = set of char; 

VAR 

odd: [STATIC] a := Cl, 3, 5], 

vowels: c, 

list_1, 

List_2: ch; 

vowels := $c C'a', 'e', ’i*, 'o', 'u'D; 
list_1 := $ch C'x', *y ', 'z']; 
list~2 := - $ch C'x', *y', 'z']; 
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Storage Types 

Storage types represent structures to which variables can be added, deleted, 
and referenced under program control. (The statements used to access the 
storage types are described under Storage Management Statements in 
chapter 5.) There are two storage types: 

• Sequences 

• Heaps 


Sequences 

A sequence type is a storage structure whose components are referenced 
sequentially using pointers. These pointers are constructed by the NEXT and 
RESET statements (described in chapter 5). 

Use this format to specify a sequence type: 

SEQ ({REP number OF] type {,{REP number OF] type}...) 

number 

Positive integer constant expression. This is an optional parameter 
specifying the number of repetitions of the specified type. 

type 

A fixed type that can be a user-defined type name; one of the 
predefined types integer, character, boolean, real, or cell; or a 
structured type using the preceding types. 

You can repeat the phrase REP number OF type as many times as desired. It 
specifies that storage must be available to hold the indicated number of 
occurrences of the named types simultaneously. The types that are actually 
stored in a sequence do not have to be the same as the types specified in the 
declaration, but adequate space must have been allocated to hold those types 
in the declaration. In other words, if a sequence is declared with several 
repetitions of integer type, the space to hold these integers has to be 
available, but it might actually hold strings or boolean values. 

Sequence types are equivalent if they have the same number of REP phrases 
and corresponding phrases are equivalent. Two REP phrases are equivalent 
if they have the same number of repetitions of equivalent types. 

Assignment to another sequence is the only operation permitted on 
sequences. 
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Heaps 

A heap type is a storage structure whose components are allocated explicitly 
by the ALLOCATE statement and released by the FREE and RESET 
statements (described in chapter 5). They are referenced by pointers 
constructed by the ALLOCATE statement. 

Use this format to specify a heap type: 

HEAP ({REP number OF\ type {,{REP number OF} type}...) 

number 

Positive integer constant expression. This is an optional parameter 
specifying the number of repetitions of the specified type. 

type 

A fixed type that can be a user-defined type name; one of the 
predefined types integer, character, boolean, real, or cell; or a 
structured type using the preceding types. 

You can repeat the phrase REP number OF type as many times as desired. It 
specifies that storage must be available to hold the indicated number of 
occurrences of the named types simultaneously. The types that are actually 
stored in a heap do not have to be the same as the types specified in the 
declaration, but adequate space must have been allocated to hold those types 
in the declaration. In other words, if a heap is declared with several 
repetitions of integer type, the space to hold these integers has to be 
available, but it might actually hold strings or boolean values. 

Heap types are equivalent if they have the same number of REP phrases and 
corresponding phrases are equivalent. Two REP phrases are equivalent if 
they have the same number of repetitions of equivalent types. 

The default heap can be managed with the ALLOCATE and FREE 
statements in the same way as a user-defined heap. For further information, 
refer to the descriptions of these statements in chapter 5. 
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Adaptable Types 

An adaptable type is a type that has indefinite size or bounds; it adapts to 
data of the same type but of different sizes and bounds. The types described 
thus far in this chapter are fixed types. An adaptable type differs from a 
fixed type in that the storage required for a fixed type is constant and can be 
determined before execution. Storage for an adaptable type is determined 
during program execution. 

An adaptable type can be a string, array, record, sequence, or heap. An 
adaptable type can be used to define formal parameters in a procedure and 
adaptable pointers. Pointers are the mechanism used for referencing 
adaptable variables. 

The size of an adaptable type must be fixed during execution. This can be 
done in one of three ways: 

• If the adaptable type is a formal parameter to a procedure or function, the 
size is fixed by the actual parameters when the procedure or function is 
called. You can determine the length of an actual parameter string using 
the STRLENGTH function, and the bounds of an act.-al parameter array 
using the UPPERBOUND and LOWERBOUND functions. (For further 
information, refer to the description of the appropriate function in chapter 
6 .) 

• An adaptable pointer type on the left side of an assignment statement is 
fixed by the assignment operation. It can be assigned any pointer whose 
current type is one of the types that the adaptable type can take on. 

• An adaptable type can be fixed explicitly using the storage management 
statements (described in chapter 5). 

An adaptable type is declared with an asterisk taking the place of the size or 
bounds normally found in the type or variable declaration. 


Adaptable Strings 

Use this format to specify an adaptable string: 

STRING ( * {<= length}) 
length 

Optional parameter specifying the maximum length of the adaptable 
string. If omitted, 65,535 characters is assumed. 

If the string exceeds the maximum allowable length, an error occurs. 

Two adaptable string types are always equivalent. 
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Adaptable Arrays 

Use this format to specify an adaptable array: 

[PACKED] ARRAY [{lower_bound *] OF type 
PACKED 

Optional packing parameter. When specified, the elements of the array 
are mapped in storage in a manner that conserves storage space, 
possibly at the expense of access time. If omitted, the array is 
unpacked; that is, the elements are mapped in storage to optimize 
access time rather than to conserve space. (The array itself is always 
mapped into an addressable memory location.) For further information 
on how data is stored in memory, refer to appendix D, Data 
Representation in Memory. 

If the array contains structured types (such as records), the elements of 
that type (the fields in the records) are not automatically packed. The 
structured type itself must be declared packed. 

lower _bound 

A constant integer expression that specifies the lower bound of the 
adaptable array. This parameter is optional, but its use is encouraged. 
Omission of this parameter (only the * appears) indicates it is an 
adaptable bound of type integer. 

type 

Type of the elements within the array. The type can be any defined 
type except an adaptable type (that is, an adaptable string, array, 
record, sequence, or heap). All elements must be of the same type. 

Only one dimension can be adaptable in an array and that dimension must 
be the outermost (first one in the declaration). 

Adaptable arrays adapt to a specific range of subscripts. An adaptable array 
can adapt to any array with the same packing attribute, equivalent subscript 
bounds, and equivalent component types. If a lower bound is specified in the 
adaptable array declaration, both arrays must also have the same lower 
bound. 

Adaptable array types are equivalent if they have the same packing 
attributes and equivalent component types, and if their corresponding array 
and component subscript bounds are equivalent. Two subscript bounds that 
contain asterisks only are always equivalent. Two subscript bounds that 
contain identical lower bounds are equivalent. 
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Adaptable Records 

An adaptable record contains zero or more fixed fields followed by one 
adaptable field that is a field of an adaptable type. 

Use this format to specify an adaptable record: 

[PACKED] RECORD 

[fixed_field_name ■' {ALIGNED [[offset MOD base]}} type}...'} 
adaptable_ field_name : [ALIGNED {[offset MOD base]}} 
adaptable_type 
RECEND 

PACKED 

Optional packing parameter. When specified, the fields of a record are 
mapped in storage in a manner that conserves storage space, possibly 
at the expense of access time. If omitted, the record is unpacked; that 
is, the fields are mapped in storage to optimize access time rather than 
to conserve space. For further information on how data is stored in 
memory, refer to appendix D, Data Representation in Memory. 

If a field is a structured type (such as another record), the elements of 
that type are not packed automatically. The structured type itself must 
be declared packed. 

fixed _ fie Id name 

Name identifying a particular fixed field. The name must be unique 
within the record. 

ALIGNED 

Optional alignment parameter. If specified, it can appear alone, or with 
an offset in the form: 

ALIGNED [offset MOD base] 

When a field is aligned, it is mapped in storage so that it is directly 
addressable. This means the field begins on an addressable boundary 
to facilitate rapid access to the field. This may negate some of the effect 
of packing the record. For further information, refer to Alignment 
earlier in this chapter. 


t If you specify more than one fixed (nonadaptable) field, you must separate 
them with commas. 
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[offset MOD base] 

Optional offset to be used in conjunction with the ALIGNED 
parameter. This offset causes the field to be mapped to a particular 
hardware address relative to the specified base and offset. Filler is 
created if necessary to ensure that the field begins on the specified 
addressable unit. 

offset 

An integer constant. Offset must be less than base. 
base 

An integer constant that must be divisible by 8. For automatic 
variables, the base can only be 8. 

type 

Any defined type, including another record, but not an adaptable type. 

adaptable_field_name 

Name identifying the adaptable field. 

adaptable _ type 
An adaptable type. 

An adaptable record can adapt to any record whose types are the same 
except for the last field. That last field must be one to which the adaptable 
field can adapt. 

Two adaptable record types are equivalent if they have the same packing 
attributes, the same alignment, the same number of fields, and 
corresponding fields with identical names and equivalent types. 
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Adaptable Sequences 

Use this format to specify an adaptable sequence: 

SEQ (*) 

An adaptable sequence can adapt to a sequence of any size. 
Two adaptable sequence types are always equivalent. 
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Adaptable Heaps 

Use this format to specify an adaptable heap: 

HEAP {*) 

An adaptable heap can adapt to a heap of any size. 
Two adaptable heap types are always equivalent. 
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This chapter describes expressions and statements that can be used within a 

CYBIL program, procedure, or function. 
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Expressions 

Expressions are made up of operands and operators. Operators act on 
operands to produce new values. (Constant expressions are evaluated to 
provide values for constants. Refer also to Constant Expressions in chapter 
2 .) 

In general, operations involving nonequivalent types are not allowed; one 
type cannot be used where another type is expected. Exceptions are noted in 
the following descriptions. 


Operands 

Operands hold or represent the values to be used during evaluation of an 
expression. An operand can be a variable, constant, name of a constant, set 
value constructor, function reference (either standard function or user- 
defined function), pointer to a procedure name, pointer to a variable, or 
another expression enclosed in parentheses. 

The value of a variable being used as an operand is the last value assigned 
to it. A constant name is replaced by the constant value associated with it in 
the constant declaration. 

A function reference causes the function to be executed; the value returned by 
the function takes the place of the function reference in the expression. 
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Operators 

Operators cause an action to be performed on one operand or a pair of 
operands. Many of the operators can be used only on basic types; they will be 
noted in their individual descriptions. Some operators can be used on sets. 
Although they are discussed in the individual descriptions that follow, for a 
more detailed description also refer to Set Operators later in this chapter. 

An operation on a variable or component of a variable that has an undefined 
value will produce an undefined result. 

There are five kinds of operators, many of which are identified by reserved 
symbols. They are listed next in the order in which they are evaluated from 
highest to lowest precedence. 

• Negation operator (NOT) 

• Multiplication operators ( * , DIV, / , MOD, and AND) 

• Sign operators ( + and -) 

• Addition operators (+, - , OR, and XOR) 

• Relational operators (<,<=,>,>=, = ,<>, and IN) 

In relational operators that consist of two symbols (that is, <=, >=, 

and < >), do not separate the symbols with a space or any other character; 

the symbols must appear together. 

When an expression contains two or more operators of the same precedence, 
operations sire performed from left to right. The only way to explicitly change 
the order of evaluation is to use parentheses. Parentheses specify that the 
expression inside them should be evaluated first. 


Negation Operator 

The negation operator, NOT, applies only to boolean operands. 
NOT TRUE equals FALSE. NOT FALSE equals TRUE. 


Multiplication Operators 

The multiplication operators perform multiplication and set intersection (*), 
integer quotient division (DIV), real quotient division (/), remainder division 
(MOD), and the logical AND operation (AND). Table 5-1 shows the 
multiplication operators, the permissible types of their operands, and the 
type of result they produce. 
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Table 5-1. Multiplication Operators 


Operator 

Operation 

Type of 

Operands 

Type of 
Result 

* 

Multiplication 

Integer or subrange 
of integer 

Integer 



Real 

Real 

* 

Set intersection 

Set of a scalar type 

Set of the 
same type 

DIV 

Integer quotientf 

Integer or subrange 
of integer 

Integer 

/ 

Real quotient 

Real 

Real 

MOD 

Remainder^ 

Integer or subrange 
of integer 

Integer 

AND 

Logical ANDftt 

Boolean 

Boolean 


t Integer quotient refers to the whole number that results from a division 
operation. The remainder is ignored. A more formal definition is: for 
positive integers a, b, and n, 


a DIV b = n 

where n is the largest integer so that b * n <= a. 

For one or two negative integers, 

(-a) DIV b = (a) DIV (-b) = - (a DIV b) and 
(-a) DIV (-b) = a DIV b 

tt Remainder refers to the remainder of a division operation. A more 
formal definition is: 

a MOD b = a - (a DIV b) * b 

ttt TRUE AND FALSE = FALSE 
TRUE AND TRUE = TRUE 
FALSE AND FALSE = FALSE 
FALSE AND TRUE = FALSE 

When the first operand is FALSE, the second operand is never 
evaluated. 
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Sip Operators 

The sign operators perform the identity operation (+) and sign inversion and 
set complement operation (-). Table 5-2 shows the sign operators, the 
permissible types of their operands, and the type of result they produce. 


Table 5-2- Sign Operators 


Operator 

Operation 

Type of 
Operands 

Type of 
Result 

+ 

Identity 
(indicates a 

Integer 

Integer 


positive operand) 

Real 

Real 

- 

Sign inversion 
(indicates a 

Integer 

Integer 


negative operand) 

Real 

Real 

- 

Set complement 

Set of a 
scalar type 

Set of the 
same type 


Addition Operators 

The addition operators perform addition and set union (+), subtraction, 
boolean difference, and set difference (-), the logical OR operation (OR), and 
the exclusive OR operation (XOR). Table 5-3 shows the addition operators, 
the permissible types of their operands, and the type of result they produce. 
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Table 5-3. Addition Operators 


Operator 

Operation 

Type of 

Operands 

Type of 
Result 

+ 

Addition 

Integer or subrange 
of integer 

Integer 



Real 

Real 

+ 

Set union 

Set of a 
scalar type 

Set of the 
same type 

- 

Subtraction 

Integer or subrange 
ofinteger 

Integer 



Real 

Real 

- 

Boolean 

differencet 

Boolean 

Boolean 

- 

Set difference 

Set of a 
scalar type 

Set of the 
same type 

OR 

Logical ORft 

Boolean 

Boolean 

XOR 

Exclusive ORftt 

Boolean 

Boolean 

XOR 

Symmetric 

difference 

Set of a 
scalar type 

Set of the 
same type 


t TRUE - TRUE = FALSE 
TRUE - FALSE = TRUE 
FALSE - TRUE = FALSE 
FALSE - FALSE = FALSE 

tt TRUE OR TRUE = TRUE 
TRUE OR FALSE = TRUE 
FALSE OR TRUE = TRUE 
FALSE OR FALSE = FALSE 

When the first operand is TRUE, the second operand is never evaluated. 

fft TRUE XOR TRUE = FALSE 
TRUE XOR FALSE = TRUE 
FALSE XOR TRUE = TRUE 
FALSE XOR FALSE = FALSE 
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Relational Operators 

The relational operators (<, <=, >, >=, =, < >, and IN) test whether the 
following given conditions are true or false: less than (<), less than or equal 
to or subset of a set (<=), greater than (>), greater than or equal to or a 
superset of a set (>=), equal to or set identity (=), not equal to or set inequality 
(< >), and set membership (IN). 

Because relational operators are valid on so many different types, some 
special points about each type are noted next. Following these comments, 
table 5-4 lists the relational operators and the permissible types of their 
operands; they always produce a boolean type result. 

Comparison of Scalar Types 

The comparison operators (<,<=,>,>=, = , and < >) are allowed only 
between operands of the same scalar type or between a substring of length 1 
and a character. 

For integer type operands, the relationships all have their usual meaning. 

For character type operands, each character is essentially mapped to its 
corresponding integer value according to the ASCII collating sequence. (This 
is the same operation performed by the $INTEGER function described in 
chapter 6.) The operands and relational operators are then evaluated using 
the characters’ integer values. 

For boolean type operands, FALSE is always considered to be less than 
TRUE. 

For ordinal type operands, operands are equal only if they are the same 
value; otherwise, they are not equal. For the other relational operators, each 
ordinal is essentially mapped to the corresponding integer value of its 
position in the ordinal list where it is defined. (This is the same operation 
performed by the $INTEGER function described in chapter 6.) The operands 
and relational operators are then evaluated using the ordinals’ integer 
values. For an example, refer to the discussion of ordinal types under Scalar 
Types in chapter 4. 

Operands that are a subrange of a scalar type can be compared with 
operands of the same type, including another subrange of the same type. 
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Comparison of Floating-Point Types 

All of the comparison operators are valid between operands of the real type. 


Comparison of Pointer Types 

Two pointers can be compared if they are pointers to equivalent or 
potentially equivalent types. (For further information on equivalent types, 
refer to Equivalent Types in chapter 4.) For potentially equivalent types, one 
or both of the pointers can be pointers to adaptable or bound variant types. 
The current type of such a pointer must be equivalent to the type of the 
pointer with which it is being compared; if it is not, the operation is 
undefined. 

Pointers can be compared for equality and inequality only. Two pointers are 
equal if they designate the same variable or if they both have the value NIL. 
A pointer of any type can be compared with the value NIL. Two pointers to a 
procedure are equal if they designate the same declaration of a procedure. 

Comparison of Relative Pointers 

Two relative pointers can be compared only if they are of equivalent types. 
Two relative pointers are equal if they can be converted to equal pointers 
using the #PTR function (described in chapter 6). 

Comparison of String Types 

All of the comparison operators are valid between operands that are strings. 
If the lengths of the two string operands are unequal, spaces are added to the 
right of the shorter string to fill the field. 

Strings are compared character by character from left to right; that is, each 
character from one string is compared with the character in the 
corresponding position of the second string. Each character is compared 
using the same method as for operands of character type; the integer value of 
the character, when mapped to the ASCII collating sequence, is used. 
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Comparison of Sets and Set Membership 

Comparison operators have slightly different meanings for sets than for 
other types. The only comparison operators valid for sets are: = (meaning 
identical to), < > (meaning different from), <= (meaning the left operand is 
contained in the right operand), and >= (meaning the left operand contains 
the right operand). These operators are valid between two sets of the same 
type. Their exact meanings are detailed later in this chapter under Set 
Operators. 

The other relational operator for sets is IN. A specified operand is IN a set if 
that operand is a member of the set. The set must be of the same type or a 
subrange of the same type as the operand. The operand can be a subrange of 
the type of the set. 


Comparison of Other Types 

Invariant records can be compared for equality and inequality only. Two 
equivalent records are equal if their corresponding fields are equal. 

The following types cannot be compared: 

• Arrays or structures that contain an array as a component or field 

• Variant records 

• Sequences 

• Heaps 

• Records that contain a field of one of the preceding types 
However, pointers to these types can be compared. 
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Table 5-4. Relational Operators 


Operator 

Operation 

Type of 

Left Operand 

Type of 

Right Operand 

< 

Less than 

Any scalar 
type 

The same 
scalar type 



Real 

Real 

< = 

Less than or 
equal to 

A string 

A string of 
the same 
length 

> 

Greater than 

A string 
of length If 

A character 

> = 

Greater than or 
equal to 



= 

Equal to 

A character 

A string 
of length If 

< > 

Not equal to 



IN 

Set membership 

Any scalar 
type 

A set of the 
same type 



Real 

A set of 
real type 



A string 
of length If 

A set of 
character type 

= 

Equality (also 
called identity) 

A set of any 
scalar type 

A set of the 
same type 

< > 

Inequality 

A set of 
real type 

A set of 
real type 

< = 

Is contained in 



> = 

Contains 



< > 

Equality 

Inequality 

A nonvariant 
record type 
containing 
no arrays 

The same type 



Any pointer 
type or the 
value NIL 

The same type 
or the value 

NIL 

t The string of length 1 has the form 



STRIN G(position) 



where the length is implied. The form 


STRIN G(position, 1) 



is not valid 

in this case. 
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Set Operators 

The set operators have already been mentioned briefly in the preceding 
sections on multiplication, sign, addition, and relational operators. This 
section discusses all of them and details how they are used with sets. 

The set operators perform assignment, union (+), intersection (*), difference 
(-), symmetric difference (XOR), negation (-), identity or equality (=), 
inequality (< >), inclusion (<=), containment (>=), and membership (IN). 

Assignment is discussed under Sets in chapter 4. The next five operations 
(union, intersection, difference, symmetric difference, and negation) all 
produce results that are sets. They are described in table 5-5. The remaining 
operations (identity, inequality, inclusion, containment, and membership) 
produce boolean results. They are described in table 5-6. 

The relational operations described in table 5-6 take place only after any 
operations described in table 5-5 have been performed. 
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Table 5-5. Operations That Produce Sets 


Operator 

Operation 

Description of Operation 

+ 

Union 

The resulting set consists of all members 
of both sets. The result of A + B is all 
elements of sets A and B. 


Difference 

The resulting set consists of the members 
in the lefthand set that are not in the 
righthand set. The result of A - B is the 
elements of A that are not in B. This 
operation differs from negation in that 
two operands Eire present. 

* 

Intersection 

The resulting set consists of the members 
that Eire in both sets. The result of A * B 
is all elements that are in both A and B. 


Negation 

(complement) 

The resulting set consists of the members 
of the set’s type that are not in the set. 

The result of -A is all elements of A’s 
type that are not in A. This operation 
differs from the difference operation in 
that only one operand is present. 

XOR 

Symmetric 

difference 

The resulting set consists of the members 
of either but not both sets. The result of 

A XOR B is all elements in A or B that 
are not common to both A and B. 
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Table 5-6. Operations That Produce Boolean Results 


Operator 

Operation 

Description of Operation 


Equality 

(identity) 

The resulting value is TRUE if every 
member of one set is present in the other 
set and vice versa. A = B is TRUE if 
every element of A is in B and every 
element of B is in A. It is also TRUE if A 
and B are both empty sets. In any other 
case, it is FALSE. 

< > 

Inequality 

The resulting value is TRUE if not every 
member of one set is a member of the 
other set. A < > B is TRUE if A = B is 
FALSE. 

< = 

Inclusion 

The resulting value is TRUE if every 
member of the lefthand set is also a 
member of the righthand set. A <= B is 
TRUE if every element of A is in B. It is 
also TRUE if A is an empty set. In all 
other cases, it is FALSE. 

> = 

Containment 

The resulting value is TRUE if every 
member of the righthand set is also a 
member of the lefthand set. A >= B is 
TRUE if every element of B is in A (that 
is, B <= A). 

IN 

Membership 

This operation differs somewhat from 
the others in that it can specify as an 
operand a value or a variable rather 
than a set. It has the form 



scalar IN set 



where scalar can be a value (including a 
subrange) or a variable. The resulting 
value is TRUE if the scalar is of the 
same type as the type of the set, and is 
an element within the set. A IN B is 
TRUE if A is the same type as the set B 
and A is an element of B. 
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Statements 

Statements specify actions to be performed. Unlike declarations, statements 
can be executed. They can appear only in a program, procedure, or function. 

A statement list is an ordered sequence of statements. In a statement list, a 
statement is separated from the one following it by a semicolon. Two 
consecutive semicolons indicate an empty statement, which means no action. 

Statements can be divided into four types depending on their purpose or 
nature: 

• Assignment 

• Structured 

• Control 

• Storage management 


Assignment Statement 

The assignment statement assigns a value to a variable. 

Use this format for the assignment statement: 

name := expression 
name 

Name of a variable previously declared, 
expression 

An expression that meets the requirements stated earlier in this 
chapter. Any constant or variable contained in the expression must be 
defined and have a value assigned. 


Revision A 


Expressions and Statements 


5-13 



ASSIGNMENT 


This statement is similar to the initialization part of the VAR declaration 
where you can assign an initial value to a variable. (For further information 
on initialization, refer to Variable Declaration in chapter 3.) The assignment 
statement allows you to change that value at any point in the program. The 
expression is evaluated and the result becomes the current value of the 
named variable. 

The variable cannot be: 

• A read-only variable. 

• A formal value parameter of the procedure that contains the assignment 
statement. 

• A bound variant record. 

• The tag field name of a bound variant record. 

• A heap. 

• An array or record that contains a heap. 

The type of the expression must be equivalent to the type of the variable, 
with the exceptions discussed next. Both types can be subranges of 
equivalent types. 

A character, string, or substring variable can be assigned the value of a 
character expression, a string, or a substring. If you assign a value that is 
shorter than the variable or substring to which it is being assigned, spaces 
are added to the right of the shorter string to fill the field. If you assign a 
value that is longer than the variable or substring, the value is truncated on 
the right. Assigning strings or substrings that overlap is not a valid 
operation, for example, STRING_1 := STRING_ 1(3,7); results are 
unpredictable. 
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If the variable is a pointer, its scope must be less than or equal to the scope of 
the data to which it is pointing. For example, a static pointer variable should 
not point to an automatic variable local to a procedure. When the procedure 
is left, the pointer variable will be pointing at undefined data. 

A pointer to a bound variant record can be assigned a pointer to a variant 
record that is not bound and is otherwise equivalent. 

An adaptable pointer can be assigned either a pointer to a type to which it 
can adapt, or an adaptable pointer than has been adapted to one of those 
types. Both the type of the expression and its value are assigned, thus setting 
the current type of the adaptable pointer. 

Any fixed pointer except a pointer to sequence can be assigned a pointer to 
cell. After the assignment, the #LOC function (described in chapter 6) 
performed on the fixed pointer would return the same value as the pointer to 
cell. 

A pointer to cell can be assigned any pointer type. The value assigned is a 
pointer to the first cell allocated for the variable to which the pointer being 
assigned points. 

When assigning pointers, remember that generally the object of a pointer has 
a different lifetime than the pointer variable. Automatic variables are 
released when the block in which they are declared has been executed. 
Allocated variables no longer exist when they are explicitly released with the 
FREE statement. An attempt to reference a variable beyond its lifetime 
causes an error and unpredictable results to occur. 

A variant record can be assigned a bound variant record of types that are 
otherwise equivalent. 

The colon (:) and equals sign (=) together are called the assignment operator. 
When used as the assignment operator, there can be no spaces or comments 
between the two symbols. 
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Structured Statements 


A structured statement is one that actually contains one or more statements. 
The statements contained in a structured statement are called, collectively, a 
statement list. The structured statement determines when the statement list 
contained in it will be executed. 


There are four structured statements-' 

BEGIN Provides a logical grouping of statements that performs a 
specific function. 

FOR Executes a list of statements while a variable is incremented 

or decremented from an initial value to a final value. 

REPEAT Executes a list of statements until a specified condition is true. 
The test is made after each execution of the statements. 


WHILE Executes a list of statements while a specified condition is 

true. The test is made before each execution of the statements. 


BEGIN Statement 

The BEGIN statement executes a single statement list once; there is no 
repetition. This statement provides for a logical grouping of statements that 
performs a particular function and can improve readability. 

Use this format for the BEGIN statement: 

{/label/} 

BEGIN 

statement list; 

END {/label/}', 

label 

Name that identifies the BEGIN statement and the statement list 
within it. Use of labels is optional. If you use a label before BEGIN, it 
is recommended that you use one after END, but it is not required. If 
you use labels in both places, they must match. The label name must 
be unique within the block in which you use it. 

statement list 

One or more statements. 

Declarations are not allowed with the BEGIN statement. Execution of the 
BEGIN statement ends when either the last statement in the list is executed 
or control is explicitly transferred from within the list. 
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FOR Statement 

The FOR statement executes a statement list repeatedly while a special 
variable ranges from an initial value to a final value. There are two formats 
for the FOR statement: one that increments the variable and one that 
decrements the variable. 

Use this format to increment the variable: 

{/label/} 

FOR name : = initial.value TO final, value DO 
statement list; 

FOREND {/label/}-. 

Use this format to decrement the variable: 

{/label/} 

FOR name := initial.value DOWNTO final.value DO 
statement list; 

FOREND {/label/}; 

label 

Name that identifies the FOR statement and the statement list in it. 
Use of labels is optional. If you use a label before FOR, it is 
recommended that you use one after FOREND, but it is not required. If 
you use labels in both places, they must match. The label name must 
be unique within the block in which you use it. 

name 

Name of the variable that controls the number of repetitions of the 
statement list. This variable keeps track of the number of iterations 
performed or the current position within the range of values. 

initial, value 

Scalar expression specifying the initial value assigned to the variable. 

final, value 

Scalar expression specifying the final value to be assigned to the 
variable if the statement ends normally. If the statement ends 
abnormally or as the result of an EXIT statement, this may not be the 
actual final value. 

statement list 

One or more statements. 
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The variable, initial value, and final value must be of equivalent scalar types 
or subranges of equivalent types. The variable cannot be assigned a value 
within the statement list, or be passed as a reference parameter to a 
procedure called within the statement list. Either condition causes a fatal 
compilation error. The variable cannot be an unaligned component of a 
packed structure. 

When CYBIL encounters a FOR statement that increments (one containing 
the TO clause), it evaluates the initial value and final value. If the initial 
value is greater than the final value, the FOR statement ends and execution 
continues with the statement following FOREND; the statement list is not 
executed. If the initial value is less than or equal to the final value, the initial 
value is assigned to the control variable and the statement list is executed. 
Then, the control variable is incremented by one value and, for each 
increment, the statement list is executed. This sequence of actions continues 
through the final value. For example, the statement 

FOR i = 1 TO 5 DO 

FOREND; 

causes the statement list to be executed five times, that is, while I takes on 
values from 1 to 5. Then the FOR statement ends and execution continues 
with the statement following FOREND. 
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When CYBIL encounters a FOR statement that decrements (one containing 
the DOWNTO clause), it performs essentially the same process. If the initial 
value is less than the final value, the FOR statement ends and execution 
continues with the statement following FOREND. If the initial value is 
greater than or equal to the final value, the initial value is assigned to the 
control variable and the statement list is executed. The control variable is 
decremented by one value and, for each decrement, the statement list is 
executed. When the control variable reaches the final value and the 
statement list is executed the last time, the FOR statement ends. 

The initial value and final value expressions are evaluated once, when the 
statement is entered; the values are then held in temporary locations. Thus, 
subsequent assignments to initial value and final value have no effect on the 
execution of the FOR statement. 

When a FOR statement completes normally, the value of the control variable 
is that of the final value specified in the statement. This may not be the case 
if the statement ends abnormally or ends as a result of an EXIT statement. 

Example: 

Integer values are often used in FOR statements, but any scalar type can be 
used. The following example executes a statement list while the value of a 
character variable is incremented. 

FOR control := 'a' TO 'z' DO 
FOREND; 

Each time the statement list is performed, the value of CONTROL increases 
by one value, following the normal sequence of alphabetic characters from ’a’ 
to Y; that is, after the statement list is executed once, the value of 
CONTROL changes to ’b’, and so on until the list has been executed 26 
times. 
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REPEAT Statement 

The REPEAT statement executes a statement list repeatedly until a specific 
condition is true. 

Use this format for the REPEAT statement: 

{/label /1 

REPEAT 

statement list; 

UNTIL expression; 

label 

Name that identifies the REPEAT statement and the statement list in 
it. Use of the label before REPEAT is optional; a label is not permitted 
after UNTIL. The label name must be unique within the block in 
which it is used. 

statement list 

One or more statements. 

expression 

A boolean type expression. 

The statement list is always executed at least once. After the last statement 
in the list, the expression is evaluated. Every time the expression is FALSE, 
the statement list is executed again. When the expression is TRUE, the 
REPEAT statement ends and execution continues with the statement 
following the UNTIL clause. 

The statement list can contain nested REPEAT statements. 

Example: 

In this example, the statement list (mod operation and assignments) is 
executed once. If J is not equal to zero, it is executed again and continues 
until J is equal to zero. 

REPEAT 

k := i MOD j; 
i := j; 
j := k; 

UNTIL j = 0; 


5-20 CYBIL Language Definition 


Revision A 






WHILE 


WHILE Statement 

The WHILE statement executes a statement list repeatedly while a specific 
condition is true. 

Use this format for the WHILE statement 
{/label/} 

WHILE expression DO 
statement list; 

WHILEND {/label /}; 

label 

Name that identifies the WHILE statement and the statement list in it. 
Use of labels is optional. If you use a label before WHILE, it is 
recommended that you use one after WHILEND, but it is not required. 
If you use labels in both places, they must match. The label name must 
be unique within the block in which you use it. 

expression 

A boolean type expression. 

statement list 

One or more statements. 
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If the boolean expression is evaluated as TRUE, the statement list is 
executed. After the last statement in the list, the expression is again 
evaluated. Every time the expression is TRUE, the statement list is executed. 
When the expression is FALSE, the WHILE statement ends and execution 
continues with the statement following WHILEND. If the expression is 
FALSE in the initial evaluation, the statement list is never executed. 

Example: 

In this example, the expression TABLE[I] < > 0 is evaluated; an element of 
the array TABLE is compared to 0. While the expression is true (the element 
is not 0), I is incremented. This causes the next element of the array to be 
checked. When the expression is false, the statement list is not executed. 
Execution continues with the statement following WHILEND. I is the 
position of an element in the array that is 0. 

/check_for_zero/ 

WHILl table CiD <> 0 DO 
i := i + 1; 

WHILEND /check_for_zero/; 

The preceding example assumes, of course, that the array contains an 
element with the value 0. If not, the WHILE statement list executes in an 
infinite loop. In either the WHILE expression or the statement list, there 
must be a check. One solution is to set a variable, TABLE_MAX, to the 
maximum number of elements in the array and check it before executing the 
statement list, as in: 

WHILE (i < tablejnax) AND (table Ci] <> 0) DO 

Now both expressions must be true before the statement list is executed. If 
either is false, execution continues following WHILEND. 
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Control Statements 


A control statement can change the flow of execution of a program by 
transferring control from one place in the program to another. 

There are five control statements: 


IF 

CASE 

CYCLE 


EXIT 


RETURN 


Executes one statement list if a given condition is true; ends 
the statement or executes another statement list if the 
condition is false. 

Executes one statement list out of a set of statement lists 
depending on the value of a given expression. 

Causes the remaining statements in a repetitive statement 
(FOR, REPEAT, or WHILE) to be skipped and the next 
iteration of the statement to take place. 

Unconditionally stops execution within a procedure, 
function, or a structured statement (BEGIN, REPEAT, 
WHILE, and FOR). 

Returns control from a procedure or function to the point at 
which it was called. 


Procedure and function calls also transfer control of an executing program. 
Functions are discussed in chapter 6 and procedures are discussed in 
chapter 7. 
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IF Statement 

The IF statement executes or skips a statement list depending on whether a 
given condition is true or false. 

Use this format for the IF statement 

IF expression THEN 
statement list; 

{ELSEIF expression THEN 
statement list;}... 

{ELSE 

statement list;} 

IFEND; 

expression 
A boolean expression. 

statement list 

One or more statements. 

The ELSEIF and ELSE clauses are optional. The ELSEIF clause contains 
another test condition that is evaluated only if the preceding condition 
(expression) is false. The ELSE clause provides a statement list that is 
executed unconditionally when the preceding expression is false. 

When an expression is evaluated as true, the statement list following the 
reserved word THEN is executed. When the list is completed, execution 
continues with the first statement following IFEND. If the expression is 
false, execution continues with the next clause or reserved word in the IF 
statement format (that is, ELSEIF, ELSE, or IFEND). 

If the next reserved word in the IF statement format is IFEND, execution 
continues with the first statement following it. 
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If the next reserved word is ELSEIF, the expression contained in that clause 
is evaluated; if true, the statement list that follows is executed. Otherwise, 
execution continues with the next reserved word in the IF statement format. 

If the next reserved word is ELSE, the statement list that follows is always 
executed. You get to this point only if the preceding expression(s) is false. 

Additional IF statements can be contained (nested) in any of the statement 
lists. A consistent style of indentation or spacing greatly improves 
readability of such statements. 

If the ELSE clause is included in a nested IF statement, the clause applies to 
the most recent IF statement. 

Examples: 

In this example, Y is assigned to X only if X is less than Y. 

IF x < y THEN 
x := y; 

I FEND; 

In the next example, Z is always assigned one of the values 1, 2, 3, or 4 
depending on the value of X. 

IF x <= 5 THEN 
z := 1; 

ELSEIF x > 30 THEN 
z := 2; 

ELSEIF x = 15 THEN 
z := 3; 

ELSE 
z := 4; 

I FEND; 
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CASE Statement 

The CASE statement executes one statement list out of a set of lists based on 
the value of a given expression. 

Use this format for the CASE statement 

CASE expression OF 
= value {.value}... - 
statement list; 

(= value {.value}... = 
statement list;}... 

{ELSE statement list;} 

CASEND; 

expression 

A scalar expression. The expression must be of the same type as the 
value or values that follow. 

value 

One or more constant scalar expressions or a subrange of constant 
scalar expressions. A subrange indicates that all of the values included 
in the subrange are acceptable values. If you specify two or more 
values, separate them with commas. The values must be of the same 
type as the expression. Values can be in any order, not strictly 
sequential. Values must be unique within the CASE statement. 

statement list 

One or more statements. 

You define a set of possible values that a variable or expression can have. 
With one or more of the values you associate a statement list using 
the format 


= value = 

statement list; 

When the CASE statement is executed, the expression is evaluated and the 
statement list associated with the current value of the expression is executed. 
If the current value is not found among those in the CASE statement, 
execution continues with the ELSE clause. If ELSE is omitted and the value 
is not found in the CASE statement, the program is in error. After any one of 
the statement lists is executed, execution continues with the statement 
following CASEND. 
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Examples: 

In this example, I is a variable that is expected to take on one of the values 1 
through 4. If its value is 1, the first statement list (X : = X + 1) is executed and 
control goes to the statement following CASEND. If the value of I is 2, the 
second list is executed, arid so on. 

CASE i OF 

x := x + 1; 

= 2 = 

x := x + 2; 

= 3 = 

x := x + 3; 

= 4 = 

x := x + 4; 

CASEND; 

In the next example, OPERATOR is a variable that is expected to take on 
values of PLUS, MINUS, or TIMES. Depending on the current value of 
OPERATOR, the associated statement is executed. 

CASE operator OF 
= plus = 
x := x + y; 

= minus = 
x := x - y; 

= times = 
x := x * y; 

CASEND; 
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CYCLE Statement 

The CYCLE statement can be included in the statement list of a repetitive 
statement (FOR, REPEAT, or WHILE) and causes any statements following 
it to be skipped and the next iteration of the repetitive statement to take 
place. 

Use this format for the CYCLE statement 

CYCLE /label/ 
label 

Name that identifies the repetitive statement in which the CYCLE 
statement is contained. 

The CYCLE statement is usually used in conjunction with an IF statement, 
as in: 

/label/ 

repetitive statement 
IF expression THEN 
CYCLE /label/; 

IFEND; 

remainder of statement list; 
end of repetitive statement; 

The IF statement tests for a condition that, if true, causes the CYCLE 
statement to be executed. Then the remaining statements of the repetitive 
statement are skipped and execution continues with whatever would 
normally follow the statement list, either another cycle of the repetitive 
statement or the next statement following the end of the repetitive statement. 
If the condition in the IF statement is false, the remaining statements in the 
repetitive statement are executed. 

If not contained in a repetitive statement, the CYCLE statement is diagnosed 
as a compilation error. 
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Example: 

This example finds the smallest element of an array TABLE. On the first 
execution, X (the first element of the array) is assumed to be smallest. If X is 
smaller than succeeding elements of the array, the CYCLE statement is 
executed; the remainder of the statements are then skipped, and the next 
iteration of the FOR statement occurs. If an element smaller than X is found, 
the CYCLE statement is ignored and the rest of the statement list is 
processed; X is replaced by the smaller element. If N has not yet been 
reached, the FOR statement continues. When N is reached, X will contain the 
smallest element of the array. 

x := table [ID; 

/find_smallest/ 

FOlfk := 2 TO n DO 

IF x < table CkD THEN 
CYCLE /find_smallest/; 

IFEND; 

x := table CkD; 

FOREND /find_smallest/; 
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EXIT Statement 

The EXIT statement causes an unconditional exit from a procedure, function, 
or a structured statement (BEGIN, FOR, REPEAT, and WHILE). 

Use this format for the EXIT statement 

EXIT name; 
name 

Name that identifies the procedure, function, or statement. For a 
procedure or function, it is the procedure or function name. For a 
structured statement, it is the statement label; in this case the format 
could be shown as EXIT /label/. 

When the EXIT statement is encountered, execution of the named procedure, 
function, or statement is automatically stopped and execution resumes with 
the statement that would follow normal completion. For a procedure or 
function, it is the statement that would normally follow the procedure or 
function call. For a structured statement, it is the statement following the 
end of the structured statement (END, FOREND, UNTIL expression, and 
WHILEND). 

The EXIT statement must be within the scope of the procedure, function, or 
statement it names. Otherwise, it has no meaning and is diagnosed as a 
programming error. 

With a single EXIT statement, you can exit several levels of procedures, 
functions, or statements; they need not be exited separately. (This is 
sometimes referred to as a nonlocal exit.) If the EXIT statement is executed 
in a nested recursive procedure or function, it is the most recent invocation of 
the procedure or function and any intervening procedures or functions that 
are exited. 
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RETURN Statement 

The RETURN statement completes the execution of a procedure or function 
and returns control to the program, procedure, or function that called it. 

Use this format for the RETURN statement: 

RETURN; 

If omitted at the end of a procedure or function, the RETURN statement is 
assumed. 
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Storage Management Statements 

Storage management statements allow you to manipulate components of 
sequence and heap types, and put variables in the run-time stack. 

There are five storage management statements: 

RESET Resets the pointer in a sequence or releases all the 

variables in a user-defined heap. 

NEXT Creates or accesses the next element of a sequence given a 

starting element. 

ALLOCATE Allocates storage for a variable in a heap. 

FREE Releases a variable from a heap. 

PUSH Allocates storage for a variable in the run-time stack. 

Sequences use the RESET and NEXT statements. Heaps use the RESET, 
ALLOCATE, and FREE statements. The run-time stack uses the PUSH 
statement. (Refer to Storage Types in chapter 4 for further information on 
sequences and heaps.) The NEXT and ALLOCATE statements can also be 
used to allocate space in a segment access file. Accessing a file as a memory 
segment is described in the CYBIL Sequential and Byte Addressable Files 
manual. That manual also compares use of the default heap and run-time 
stack with use of a segment access file for data storage. 

In the NEXT, ALLOCATE, and PUSH statements, you must specify a 
pointer to the variable to be manipulated so that sufficient space can be 
allocated for that type. This pointer can be a pointer to a fixed type, a pointer 
to an adaptable type, or a pointer to a bound variant record type. Space is 
then allocated for a variable of the type to which the pointer can point. This 
pointer is also used to access the variable. When space is allocated, CYBIL 
returns the address of the variable to the pointer. Therefore, to reference a 
variable in a sequence, heap, or the run-time stack, you indicate the object of 
the pointer in this form: pointer name . 
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If you specify a fixed type pointer, the statement uses a variable of the type 
designated by that pointer variable. If you specify an adaptable type pointer 
or bound variant record type pointer, you must also indicate the size of the 
adaptable type or the tag field of the variant record to be used. This causes a 
fixed type to be set and the adaptable or bound variant record pointer 
designates a variable of that fixed type. That particular fixed type is 
designated until it is reset by a subsequent assignment or another storage 
management statement. 


To indicate the size of an adaptable pointer or the tag field of a bound 
variant record pointer, you use the format: 

pointer: [size] 


pointer 

Name of an adaptable pointer variable or a bound variant record 
pointer variable. 


size 

Fixed amount of space required for the variable designated by pointer. 
This is also referred to as the size fixer. You set the size of the 
adaptable type the same way you specify the size of the corresponding 
unadaptable (fixed) type. For example, in a variable or type 
declaration, you specify the size of a fixed array with subscript bounds, 
usually a subrange of ’’scalar expression..scalar expression”. You set 
the size of an adaptable array here using the same form. Summarized 
next are the forms used to set the size of all possible adaptable types. 
For more detailed information, refer to the descriptions of the 
corresponding fixed types in chapter 4. 


Pointer Type_Form Used to Set Size 


Adaptable array 
Adaptable string 

Adaptable heap 

Adaptable sequence 

Adaptable record 


scalar expression .. scalar expression 

A positive integer expression specifying the 
length of the string 

[{REP positive integer expression OF] fixed 
type name \,\REPpositive integer expression 
OF] fixed type name]...] 

[{REP positive integer expression OF] fixed 
type name {,{ REP positive integer expression 
OF] fixed type name]...] 

One of the forms used for an adaptable array, 
string, heap, or sequence 


Bound variant record A scalar expression or one or more 

constant scalar expressions followed by an 
optional scalar expression 
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If an adaptable array had a lower bound specified in its original declaration, 
the lower bound specified here must match that value. For an adaptable 
record, the form used must be a value and type to which the record can 
adapt. For a bound variant record, the order, types, and values used must be 
valid for a variant of the record; all but the last of the expressions must be 
constant expressions. 

Examples: 

This example declares a type that is an adaptable array named 
AD APT_ ARRAY. PTR is a pointer to that type. BUNCH is a heap with 
space for 100 integers. The heap BUNCH is reset; that is, any existing 
elements are released. Space is then allocated in the heap for a variable of 
the type designated by PTR. That variable is of type ADAPT_ ARRAY (an 
array of integers) and it has fixed subscript bounds of from 1 to 15. PTR now 
points to that array. 

TYPE 

adapt_array = array Cl * 3 of integer; 

VAR 

ptr: “adapt_array, 

bunch: HEAP (REP 100 of integer); 

RESET bunch; 

ALLOCATE ptr: Cl .. 15] IN bunch; 

The following example shows the setting of an adaptable sequence. Notice 
that two sets of brackets are required in the PUSH statement. 

VAR 

ptr: "SEQ ( * ); 

PUSH ptr: CCREP 10 OF integer, REP 22 OF char]]; 
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RESET Statement 

The RESET statement operates on both sequences and heaps. In a sequence, 
it resets the pointer to the beginning of the sequence or to a specific variable 
within the sequence. In a heap, it releases all the variables in the heap. 

The RESET statement must appear before the first NEXT statement (for a 
sequence) or ALLOCATE statement (for a user-defined heap). This ensures 
that the sequence is at the beginning or the heap is empty. If you reserve 
space by using a NEXT or ALLOCATE statement before the RESET 
statement, the program is in error. 


RESET in a Sequence 

This statement sets the current element being pointed to in a sequence. 

Use this format for the RESET statement in a sequence: 

RESET sequence, pointer { TO variable_pointer ) 
sequence _ pointer 

Name of a pointer to a sequence. This specifies the particular sequence. 
variable _pointer 

Name of a pointer to a particular variable within the sequence. If 
omitted, the pointer points to the first element of the sequence. 

If you did not set the value of the pointer variable with a NEXT statement 
for the same sequence, an error will occur. An error will also occur if the 
value of the pointer variable is NIL. 

The RESET statement must appear before the first occurrence of a NEXT 
statement to reset the sequence to its beginning; otherwise, the program is in 
error. 
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RESET in a Heap 

This statement releases the variables currently in a heap. 

Use this format for the RESET statement in a heap: 

RESET heap 
heap 

Name of a heap type variable. 

Space for the variables is released and their values become undefined. 

Make sure that the RESET statement appears before the first occurrence of 
an ALLOCATE statement for a user-defined heap so that the heap is empty; 
otherwise, the program is in error. 
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NEXT Statement 

The NEXT statement sets the specified pointer to designate the current 
element of the sequence and then makes the next element in the sequence the 
current element. This essentially moves the pointer along the sequence 
allowing you to assign values to and access elements. 

Use this format for the NEXT statement 

NEXT pointer {• [size ]} IN sequence_ pointer 

pointer 

Name of a pointer to a fixed type, pointer to an adaptable type, or 
pointer to a bound variant record type. The type pointed to by the 
pointer is the type of the variable in the sequence. These pointers are 
described in detail under Storage Management Statements earlier in 
this section. 

size 

Size of an adaptable type or tag field of a bound variant record type. If 
omitted, the pointer must be a pointer to a fixed type. The forms used to 
specify size are described in detail under Storage Management 
Statements earlier in this section. 

sequence_ pointer 

Name of a pointer to a sequence. This specifies the particular sequence. 

After a RESET statement, the current element is always the first element of 
the sequence. A NEXT statement assigns to the specified pointer the address 
of the current (first) element, and then makes the next element (the second) 
the new current element. Thus, the order of variables in a sequence is 
determined by the order in which the NEXT statements are executed. 

If the NEXT statement causes the new element to be outside the bounds of 
the sequence, the pointer is set to NIL. Before attempting to reference an 
element in a sequence, check for a NIL pointer value. If you use a pointer 
variable with a value of NIL to access an element, an error will occur. 

The type of the pointer you specify when data is retrieved from the sequence 
must be equivalent to the type of the pointer you used when the same data 
was stored in the sequence; otherwise, the program is in error. 
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ALLOCATE Statement 

The ALLOC ATE statement allocates storage space for a variable of the 
specified type in the specified heap and then sets the pointer to point to that 
variable. 

Use this format for the ALLOCATE statement' 

ALLOCATE pointer {•' [size ]} [ IN heap ) 

pointer 

Name of a pointer to a fixed type, adaptable type, or bound variant 
record type. These pointers are described in detail under Storage 
Management Statements earlier in this section. 

size 

Size of an adaptable type or tag field of a bound variant record type. If 
omitted, the pointer must be a pointer to a fixed type. The forms used to 
specify size are described in detail under Storage Management 
Statements earlier in this section. 

heap 

Name of a heap type variable. If omitted, the default heap is assumed. 

If there is not enough space for the variable to be allocated, the pointer is set 
to NIL. Before attempting to reference a variable in a heap, check for a NIL 
pointer value. If you use a pointer variable with a value of NIL to access 
data, an error will occur. 

The RESET statement must appear before the first occurrence of an 
ALLOCATE statement for a user-defined heap to ensure that the heap is 
empty; otherwise, the program is in error. (This is not allowed for the default 
heap.) 

The lifetime of a variable that is allocated using the storage management 
statements is the time between the allocation of storage (with the 
ALLOCATE statement) and the release of storage (with the FREE 
statement). A variable allocated using an automatic pointer must be 
explicitly freed (using the FREE statement) before the block is left, or the 
space will not be released by the program. When the block is left, the pointer 
no longer exists and, therefore, the variable cannot be referenced. If the block 
is entered again, the previous pointer and the variable referenced by the 
pointer cannot be reclaimed. 
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FREE Statement 

The FREE statement releases the specified variable from the specified heap. 
Use this format for the FREE statement 
FREE pointer {IN heap } 
pointer 

Name of the pointer variable that designates the variable to be 
released. 

heap 

Name of a heap type variable. If omitted, the default heap is assumed. 

The variable’s space in the heap is released and its value becomes undefined. 
The pointer variable designating the released variable is set to NIL. If you 
specify a variable that is not currently allocated in the heap, the results are 
unpredictable. 

Using a pointer variable with the value NIL to access data causes an error to 
occur. Releasing the NIL pointer is also an error. 
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PUSH Statement 

The PUSH statement allocates storage space on the run-time stack for a 
variable of the specified type and then sets the pointer to point to that 
variable. 

Use this format for the PUSH statement-' 

PUSH pointer {•' [size ]} 
pointer 

Name of a pointer to a fixed type, adaptable type, or bound variant 
record type. These pointers are described in detail under Storage 
Management Statements earlier in this section. 

size 

Size of an adaptable type or tag field of a bound variant record type. If 
omitted, the pointer must be a pointer to a fixed type. The forms used to 
specify size are described in detail under Storage Management 
Statements earlier in this section. 

If there is not enough space for the variable to be allocated, the pointer is set 
to NIL. The value of the variable that has just been allocated is undefined 
until a subsequent assignment to the variable is made. 

You cannot release space on the run-time stack explicitly. It is released 
automatically when the procedure containing the PUSH statement 
completes. At that time, space for the variable is released and its value 
becomes undefined. 

Example: 

This example shows the declaration of a pointer variable named ARRAY_ 
PTR that points to an adaptable array. The PUSH statement allocates space 
in the run-time stack for a fixed array of from 1 to 20 elements. Elements of 
the array can be referenced by ARRAY_PTR"[i], where i is an integer from 1 
to 20. 

VAR 

array _ptr: "array Cl * J of integer; 

PUSH array_ptr: Cl .. 20]; 
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A function is one or more statements that perform a specific action and can 
be called by name from a statement elsewhere in a program. A reference to a 
function causes actual parameters in the calling statement to be substituted 
for the formal parameters in the function declaration and then the function’s 
statements to be executed. Usually the function computes a value and 
returns it to the portion of the program that called it. 

A function differs from a procedure in that the value returned for a function 
replaces the actual function reference within the statement. A function is a 
valid operand in an expression; the value returned by the function replaces 
the reference and becomes the operand. 

The value of a function is the last value assigned to it before the function 
returns to the point where it was called. The reason for its return doesn’t 
matter; it could complete normally or abnormally. If the function returns for 
any reason before a value is assigned to the function name, results are 
undefined. 

Functions can be recursive; that is, a function can call itself. In that case, 
however, there must be some provision for ending the calls. 

You can call standard functions that are already defined in the CYBIL 
language, you can define your own functions, or you can call functions 
designed specifically for use on NOS/VE. This chapter describes all three. 

Functions that start with $ are data conversion functions. Functions that 
start with # are either system-dependent functions (that is, unique to CYBIL 
on NOS/VE) or functions whose results are system dependent. (For example, 
#SIZE is a standard function available on all variations of CYBIL regardless 
of operating system; however, its results vary depending on the system on 
which it is being used.) 


Standard Functions 

The functions described here are standard CYBIL functions. They can be 
used safely in variations of CYBIL available on other operating systems. 
Under System-Dependent Functions, later in this chapter, you’ll find 
descriptions of functions unique to CYBIL on NOS/VE. 

The functions are described in alphabetical order. 
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$CHAR 


$CHAR Function 

The $CHAR function returns the character whose ordinal number within the 
ASCII collating sequence is that of a given expression. 

Use this format for the $CHAR function call: 

$CHAR(expression) 

expression 

An integer expression whose value can be from 0 to 255. 

If you specify a value for the integer expression less than 0 or greater than 
255, an error occurs. 
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$INTEGER Function 

The $INTEGER function returns the integer value of a given expression. 

Use this format for the $INTEGER function call: 

$INTEGER(expression) 

expression 

An expression of type integer, subrange of integer, boolean, character, 
ordinal, or real. 

If the expression is an integer expression, the value of that expression is 
returned. 

If the expression is a boolean expression, 0 is returned for a false expression 
and 1 is returned for a true expression. 

If the expression is a character expression, the ordinal number of the 
character in the ASCII collating sequence is returned. 

If the expression is an ordinal expression, the ordinal number associated 
with that ordinal value is returned. The value returned for the first element 
of an ordinal type is 0, the second element is 1, and so on. 

If the expression is a real expression, the value of the expression is truncated 
to a whole number. If the number is in the range defined for integers, that 
number is returned; otherwise, an out-of-range error occurs. 
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#LOC Function 

The #LOC function returns a pointer to the first cell allocated for a given 
variable. 

Use this format for the #LOC function call: 

#LOC(name) 

name 

Name of a variable. 
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LOWERBOUND Function 

The LOWERBOUND function returns the lower bound of an array’s 
subscript bounds. 

Use this format for the LOWERBOUND function call: 

LOWERBOUND(array) 

array 

An array variable or the name of a fixed array type. 

The type of the value returned is the same as the type of the array’s subscript 
bounds. 

Example: 

Assuming the following declaration has been made 

VAR 

x: array £1 .. 10CD of boolean, 
y: array C'a' .. 't'] of integer; 

the value of LOWERBOUND(X) is 1; the value of LOWERBOUND(Y) is ’a’. 
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LOWERVALUE 


LOWERVALLJE Function 

The LOWERVALUE function returns the smallest possible value that a 
given variable or type can have. 

Use this format for the LOWERVALUE function call: 

LOWERVALUE(name) 

name 

A scalar variable or name of a scalar type. 

The type of the value returned is the same as the given type. 

Examples: 

Assuming the following declaration has been made 

VAR 

dozen: 1 .. 12; 

the value of LOWERVALUE(DOZEN) is 1. 

After the declarations 
TYPE 

t = (first, second, third); 

VAR 
v: t; 

the value of LOWERVALUE(V) is FIRST and the value of 
LOWERVALUE(T) is FIRST. 
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PRED Function 

The PRED function returns the predecessor of a given expression. 

Use this format for the PRED function call: 

PRED(expression) 

expression 
A scalar expression. 

If the predecessor of the expression does not exist, the program is in error. 
Example: 

The following example declares two variables, WARM and COLD, each of 
which can take on ordinal values of the type SEASONS. The variable 
WARM is assigned the value SPRING while the variable COLD is assigned 
the value WINTER. 

TYPE 

seasons = (winter, spring, simmer, falL); 

VAR 

warm: seasons, 
cold: seasons; 

warm := spring; 
cold := PRED (warm); 
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#PTR Function 

The #PTR function returns a pointer that can be used to access the object of 
a relative pointer. 

Use this format for the #PTR function call: 

#PTR(pointer_name {,parent_name}) 
pointer _ name 

Name of the relative pointer variable. 
parent_name 

Name of the variable that contains the components being designated 
by relative pointers. If omitted, the default heap is used. The variable 
can be a string, array, record, heap, or sequence type (either fixed or 
adaptable). 

Relative pointers cannot be used to access data directly. The #PTR function 
converts a relative pointer to a pointer in order to reference the object of the 
relative pointer. 

The type of the object pointed to by the returned pointer is the same as the 
type of the object pointed to by the relative pointer. If the type of the parent 
variable associated with the specified relative pointer is not equivalent to the 
type of the specified parent variable, an error occurs. 

For further information on relative pointers, refer to Pointer Types in chapter 

4. 
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$REAL Function 

The $REAL function returns the real number equivalent of a given integer 
expression. 

Use this format for the $REAL function call: 

$REAL(expression) 

expression 
An integer expression. 
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#REL Function 

The #REL function returns a relative pointer. 

Use this format for the #REL function call: 

#REL(pointer_name {,parent _name}) 
pointer _ name 

Name of the direct pointer variable. 
parent _name 

Name of the variable that contains the components being designated 
by relative pointers. If omitted, the default heap is used. The variable 
can be a string, array, record, heap, or sequence type (either fixed or 
adaptable). 

The type of the relative pointer’s object is the same as the type of the given 
direct pointer’s object. (This type was specified in the VAR declaration of the 
relative pointer variable.) The parent type of the relative pointer’s object is 
the same as the type of the specified parent variable. 

If the pointer specified in the function call does not designate an element of 
the parent variable, the result is undefined. 

Relative pointer values can be generated solely through this function. For 
further information on relative pointers, refer to Pointer Types in chapter 4. 
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#SEQ Function 

The #SEQ function returns an adaptable pointer to a sequence allocated for a 
given variable. 

Use this format for the #SEQ function call: 

#SEQ(name) 

name 

Name of a variable of any type. 

The following relationships hold between the #LOC, #SEQ, and #SIZE 
functions: 

#LOC(#SEQ(name) *) = #LOC(name) 

#SIZE(#SEQ(name) *) = #SIZE(name) 
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#SIZE 


#SIZE Function 

The #SIZE function returns the number of cells required to contain a given 
variable or a variable of a specified type. 

Use this format for the #SIZE function call: 

#SIZE(name) 

name 

Name of a variable, fixed record type, bound variant record, or an 
adaptable type. 

If you specify the name of a bound variant record type, the variant that 
requires the largest size is used. If you specify the name of an adaptable type, 
you must also supply a size fixer for the type. 

Example: 

The following example declares a procedure, FIND_SIZE, that has as its 
only parameter an adaptable array named A. When the procedure is called, 
the #SIZE function determines the size of the fixed array that was passed to 
it. 


PROCEDURE find_size (a: array Cl 


*] OF integer); 


i := #SlZE(a); 
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STRLENGTH Function 

The STRLENGTH function returns the length of a given string. 

Use this format for the STRLENGTH function call: 

STRLENGTH(string) 

string 

A string variable, name of a string type, or adaptable string reference. 

For a fixed string, the allocated length is returned as an integer subrange. 
For an adaptable string, the current length is returned. 

Example: 

The following example declares a procedure, FIND_ LENGTH, that has as 
its only parameter an adaptable string named S. When the procedure is 
called, the STRLENGTH function determines the length of the fixed string 
that was passed to it. 

PROCEDURE find_length (s: stringC*)); 
i := STRLENGTH (s); 
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SUCC Function 

The SUCC function returns the successor of a given expression. 

Use this format for the SUCC function call: 

SUCC(expression) 

expression 
A scalar expression. 

If the successor of the expression does not exist, the program is in error. 
Example: 

The following example declares two variables, HOT and COOL, each of 
which can take on ordinal values of the type SEASONS. The variable HOT 
is assigned the value SUMMER while the variable COOL is assigned the 
value FALL. 

TYPE 

seasons = (winter, spring, summer, fall); 

VAR 

hot: seasons, 
cool: seasons; 

hot := summer; 
cool := SUCC (hot); 
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UPPERBOUND Function 


The UPPERBOUND function returns the upper bound of an array’s 
subscript bounds. 

Use this format for the UPPERBOUND function call: 

UPPERBOUND(array) 


array 

An array variable or the name of a fixed array type. 

The type of the value returned is the same as the type of the array’s subscript 
bounds. 

Examples: 

Assuming the following declaration has been made 


VAR 

x: array Cl .. 1003 of boolean, 
y: array C'a' .. 't'3 of integer; 

the value of UPPERBOUND(X) is 100; the value of UPPERBOUND(Y) is’t’. 
In the following example, the value of UPPERBOUND(TABLE) is 50: 


VAR 

table: “array Cl 
ALLOCATE table: Cl 


* 3 of cell; 
503; 
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UPPERVALUE Function 

The UPPERVALUE function returns the largest possible value that a given 
variable or type can have. 

Use this format for the UPPERVALUE function call: 
UPPERVALUE(name) 
name 

A scalar variable or name of a scalar type. 

The type of the value returned is the same as the given type. 

Examples: 

Assuming the following declaration has been made 

VAR 

dozen: 1 .. 12; 

the value of UPPERVALUE(DOZEN) is 12. 

After the declarations 
TYPE 

t = (first, second, third); 

VAR 
v: t; 

the value of UPPERVALUE(V) is THIRD and the value of 
UPPERVALUE(T) is THIRD. 
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User-Defined Functions 


Function Declaration 

You define your own functions with function declarations. 

Use this format to declare a function: 

FUNCTION | [attributes]} name {(formalparameters)} • result_type;t 
{declaration _ list } 

statement, list 
FUNCEND {name}; 

attributes 

One or more of the following attributes. If you specify more than one, 
separate them with commas. 

XREF 

The function has been compiled in a different module. In this case, 
the function declaration can contain the name and formal 
parameters, but no declaration list or statement list. In the other 
module, the function must have been declared with the XDCL 
attribute and an identical parameter list. If omitted, the function 
must be defined within the module where it is called. 

XDCL 

The function can be called from outside of the module in which it is 
located. This attribute can be included only in a function declared at 
the outermost level of a module; it cannot be contained in a 
program, procedure, or another function. Other modules that call 
this function must contain the same function declaration with the 
XREF attribute specified. 


t Some variations of CYBIL available on other operating systems allow an 
additional option, the alias name, in a function declaration. If included in a 
CYBIL program run on NOS/VE, this parameter is ignored. 
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INLINE 

Instead of calling the function, the compiler inserts the actual function 
statements at the point in the code where the function call is made. 

#GATEf 

The function can be called by a function call from a higher ring level if 
the call is issued from within the call bracket of the gated function.ft If 
you specify #GATE, you must also specify the XDCL attribute. 

If you don’t specify any attributes, the function is assumed to be in the 
same module in which it is called. 

name 

Name of the function. The function name is optioned following 
FUNCEND. 

formal _parameters 

One or more parameters in the form: 

VAR name {.name}... : type 
{.name {.name}... '■ type}... 

and/or: 

name {.name}... : type 
{.name {name}... •' type}... 

The first form is called a reference parameter; the second form is called 
a value parameter. There is essentially no difference between them in 
the context of a function. However, procedures (and programs) do treat 
them differently. Both kinds of parameters can appear in the formal 
parameter list; if so, they are separated by semicolons (for example, 

I: INTEGER; VAR A: CHAR). Reference and value parameters are 
discussed in more detail later in this chapter under Parameter List. 

result _type 

The type of the result to be returned. Specify any fixed scalar, floating¬ 
point, pointer, or cell type. 

declaration _list 

Zero or more declarations. 

statement_list 

One or more statements. 


t This attribute is not supported on variations of CYBIL available on other 
operating systems. 

tt A ring level is a hardware feature. Rings provide hardware protection in 
that an unauthorized program cannot access anything at a lower ring 
level. For further information on rings, refer to the SCL Object Code 
Management manual. 


6-18 


CYBIL Language Definition 


Revision D 



USER-DEFINED FUNCTIONS 


In an assignment statement within a function, the lefthand side of the 
statement (the variable to receive the value) cannot be: 

• A nonlocal variable. 

• A formal parameter of the function. 

• The object of a pointer variable. 

User-defined functions cannot contain: 

• Procedure call statements that call user-defined procedures or NOS/VE 
procedures. 

• Parameters of type pointer to procedure. 

• ALLOCATE, FREE, PUSH, or NEXT statements that have parameters 
that are not local variables. 


Parameter List 

A parameter list is an optional list of variable declarations that appears in 
the first statement of the function declaration. In the function declaration 
format shown earlier, they are shown as formal parameters. Declarations 
for formal parameters must appear in that first statement; they cannot 
appear in the declaration list in the body of the function. 

A parameter list allows you to pass values from the calling program to the 
function. When a call is made to a function, parameters called actual 
parameters are included with the function name. The values of those actual 
parameters replace the formal parameters in the parameter list. Wherever 
the formal parameters exist in the statements within the function, the values 
of the corresponding actual parameters are substituted. For every formal 
parameter in a function declaration, there must be a corresponding actual 
parameter in the function call. 

There are two kinds of parameters: reference parameters and value 
parameters. A reference parameter has the form: 

VAR name {,name}... • type 
{,name {,name}... '■ type}... 

A value parameter has the form: 

name {,name }...: type 
{.name {.name}... -' type}... 
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In procedures, reference parameters and value parameters cause different 
actions to be taken; in functions, however, both kinds of parameters have the 
same effect. (In a procedure, the value of a reference parameter can change 
during execution of the procedure; a value parameter cannot change.) In a 
function, neither reference parameters nor value parameters can change in 
value. A formal reference parameter can be any fixed or adaptable type. A 
formal value parameter can be any fixed or adaptable type, except a heap or 
an array or record that contains a heap. 

Reference parameters and value parameters can be specified in many 
combinations. When both kinds of parameters appear together, they must be 
separated by semicolons. Parameters of the same type can also be separated 
by semicolons instead of commas, but in this case, VAR must appear with 
each reference parameter. All of the following parameter lists are valid. 

• VAR i, j: integer; a, b: char; 

• VAR i: integer; VAR j: integer; a: char; b: char; 

• a: char; VAR i, j: integer; b: char; 

• VAR i: integer, j: real; a: char, b: boolean; 

In each of the preceding examples, I and J are reference parameters; A and B 
are value parameters. 
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Referencing a Function 

The call to the function is usually contained in an expression. The call 
consists of the function name (as given in the function declaration) and any 
parameters to be passed to the function in the following format: 

name ({actualparameters 1) 

name 

Name of the function. 
actual parameters 

Zero or more expressions or variables to be substituted for formal 
parameters defined in the function declaration. If you specify two or 
more, separate them with commas. They are substituted one-for-one 
based on their position within the list; that is, the first actual 
parameter replaces the first formal parameter, the second actual 
parameter replaces the second formal parameter, and so on. For every 
formal parameter in a function declaration, there must be a 
corresponding actual parameter in the function call. 

If you did not specify any formal parameters in the function 
declaration, you can’t include any actual parameters in the function 
call. However, you must enter left and right parentheses to indicate the 
absence of parameters. In this case, the call is: 

name() 

The function can be anywhere that a variable of the same type could be. The 
value returned by a function is the last value assigned to it. If control is 
returned to the calling point before an assignment is made, results are 
unpredictable. 

The only types that can be returned as values of functions are the basic 
types: scalar, floating point, pointer, and cell. 
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Example: 

The following function finds the smaller of two integer values represented by 
formal value parameters A and B. The smaller value is assigned to MIN, the 
name of the function, and that integer value is returned. 

FUNCTION min (a, 

b: integer): integer; 

IF a > b THEN 
min := b; 

ELSE 

min := a; 

IFEND; 

FUNCEND min; 

This function could be called using the following reference: 
smaller := min (first, second); 

The value of the variable FIRST is substituted for the formal parameter A; 
the value of SECOND is substituted for B. The value returned, the smaller 
value, replaces the entire function reference; the variable SMALLER is 
assigned the smaller value. 
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System-Dependent Functions 

The functions described here can be used with CYBIL only on NOS/VE. As 
you review this section, keep in mind that programs using these functions 
cannot be transported to other operating systems and run on variations of 
CYBIL. 

To use these functions properly and efficiently, you should be familiar with 
basic hardware concepts of your computer system. This information can be 
found in volume II of the virtual state hardware reference manual. 

The functions are described in alphabetical order. 


#ADDRESS Function 

The #ADDRESS function accepts a ring number, segment number, and byte 
offset and returns a value that is of type pointer to cell. 

Use this format for the # ADDRESS function call: 

#ADDRESS(ring, segment, offset) 

ring 

Ring number, ranging from 1 to 15. 
segment 

Segment number, ranging from 0 to 4,095. 
offset 

Byte offset, ranging from -80000000 hexadecimal to 7FFFFFFF 
hexadecimal. 

Example: 

The following example uses the #ADDRESS function to set the variable 
PTR1 to a pointer to cell formed using a ring number of 11, a segment 
number of 10, and a byte offset of 0FFFF hexadecimal. 

VAR 

i/ 

j/ 

k: integer, 
ptrl: "cell; 

i := 11; 

j := 10; 

k := offff(16); 

ptrl := ^address (i, j, k); 
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#FREE_RUNNING_CLOCK 

#FREE_RUNNING_CLOCK Function 

The #FREE_RUNNING_CLOCK function returns the value of the free 
running microsecond clock. 

Use this format for the #FREE_RUNNING_CLOCK function call: 
#FREE_RUNNING_CLOCK(port) 
port 

An integer expression whose value is 0 or 1. It specifies the memory 
port to be used for reading the clock. 

The integer value returned is that of the free running clock that is 
maintained within the memory connected to the specified processor 
memory port. 

For further information on the free running microsecond clock and memory 
ports, refer to volume II of the virtual state hardware reference manual. 

Example: 

The following example sets the integer variable I to the value of the free 
running microsecond clock in the memory connected to processor memory 
port 0. 

VAR 

i: integer; 

i := #free_running_clock (0); 
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#OFFSET Function 

The #OFFSET function accepts a direct pointer and returns the integer value 
of the signed offset (byte number) contained in the pointer. 

Use this format for the #OFFSET function call: 

#OFFSET(pointer) 

pointer 

Name of a direct pointer expression. 

A pointer consists in part of the process virtual address (PVA) of the first 
byte of the object to which it is pointing. An element of the PVA is the byte 
number. This byte number is the signed offset returned. 

For further information on PVAs, refer to volume II of the virtual state 
hardware reference manual. 

Example: 

The following example finds the byte offset in the pointer PTRl. 


VAR 

ptrl: 'cell, 

byte_offset: - 80000000(16) .. 7fffffff(16); 
byte_offset := Soffset (ptrl); 

If PTR1 was formed using the following #ADDRESS function, 
ptrl := ^address (11, 10, offff(16)); 
the value of BYTE _ OFFSET would be 0FFFF hexadecimal. 
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#PREVIOUS_SAVE_AREA Function 

The #PRE VIOUS _ SAVE _ AREA function returns a pointer to the first cell 
of the previous save area. 

Use this format for the #PRE VIOUS _ SAVE _ AREA function call: 

#PREVIOUS_SAVE_AREA () 

A procedure uses an area called a stack frame to store its dynamic variables. 
If another procedure is called, hardware saves certain registers of the calling 
procedure and puts them in a stack frame save area. These registers contain 
the information required for the calling procedure to resume normal 
execution when control is returned by the called procedure. 

If procedure calls are nested, each subsequent call creates its own stack 
frame save area and the last save area becomes the previous save area. 
Pointers are kept to link the previous save areas so that as procedures 
complete and return, the system works back through the previous save areas 
using the information contained in them to resume each procedure. 

The formats of the stack frame save area and previous save area are shown 
in the CYBIL System Interface manual. For further information on the stack 
frame save area and previous save area, refer to volume II of the virtual state 
hardware reference manual. 

Example: 

The following example sets the pointer variable PSA_PTR to point to the 
first cell of the previous save area. The #CALLER_ID procedure then returns 
information about the caller of the last function. That information is 
returned in the record CALLER_RECORD. In this example, CALLER_ 
RECORD is equivalent to the object of pointer PSA_PTR (that is, CALLER_ 
RECORD = PSA_PTR“). 

TYPE 

id_rec = record 
Td: 0 .. Offffffff(16), 
recend; 

VAR 

psa_ptr: "id_rec, 
caller_record: id_rec; 

psa_ptr := #previous_save_area (); 

#caller_id (caLLer_record); 
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#READ_REGISTER Function 

The #READ_REGISTER function performs actions equivalent to the copy 
from state register (CPYSX) hardware instruction. It allows a program to 
read the contents of a process or processor register. 

Use this format for the #READ_REGISTER function call: 

#READ_REGISTER(register_id) 

registered 

An integer expression from 0 to 255 that identifies the number of the 
register to be read. Register numbers are given in volume II of the 
virtual state hardware reference manual. 

An integer value is returned. 

The #WRITE_REGISTER procedure described in chapter 7 allows a 
program to change the contents of a process or processor register. 

For further information on process and processor registers, and the CPYSX 
instruction, refer to volume II of the virtual state hardware reference manual. 

Example: 

The following example sets the integer variable J to the value of register E5, 
the Debug mask register. 

VAR 

j: integer; 

j := #read_register (0e5<16>); 
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#RING Function 


The #RING function accepts a pointer and returns the integer value of the 
ring number contained in the pointer. 

Use this format for the #RING function call: 


#RING(pomter) 

pointer 

Name of a direct pointer expression. 

Example: 

The following example finds the ring number in the pointer PTR1. 

VAR 

ptrl: “cell, 
ring_number: integer; 

ring_number := #ring (ptrl); 

If PTR1 was formed using the following #ADDRESS function, 
ptrl := tfaddress (11, 10, 0ffff(16)); 
the value of RING_ NUMBER would be 11. 
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#SEGMENT Function 

The #SEGMENT function accepts a pointer and returns the integer value of 
the segment number contained in the pointer. 

Use this format for the #SEGMENT function call: 

#SEGMENT(pointer) 

pointer 

Name of a direct pointer expression. 

Example: 

The following example finds the segment number in the pointer PTR1. 

VAR 

ptrl: -cell, 
segment_number: integer; 

segment_number := ^segment (ptrl); 

If PTR1 was formed using the following #ADDRESS function, 
ptrl := ^address (11, 10, offff(16)); 
the value of SEGMENT_NUMBER would be 10. 
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A procedure is one or more statements that perform a specific action and can 
be called by a single statement. A procedure allows you to associate a name 
with the statement list so that by specifying the name itself as if it were a 
statement, you cause the list to be executed. Declarations can be included 
and take effect when the procedure is called. A procedure call can optionally 
cause actual parameters included in the call to be substituted for the formal 
parameters in the procedure declaration before the procedure’s statements 
are executed. 

A procedure differs from a function in that: 

• A procedure can, but does not always, return a value. 

• The call to a procedure is the procedure’s name itself; a function call by 
contrast must be part of an expression in a statement. 

• There can be no value assigned to the procedure name as there is to a 
function name. 

You can call standard procedures that are already defined in the CYBIL 
language, you can define your own procedures, or you can call procedures 
designed specifically for use on NOS/VE. This chapter describes all three. 


Standard Procedures 

The STRINGREP procedure described here is a standard CYBIL procedure. 

It can be used safely in variations of CYBIL available on other operating 
systems. The last section in this chapter, System-Dependent Procedures, 
describes procedures that may not be available on other operating systems or 
that are unique to CYBIL on NOS/VE. 
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STRING REP Procedure 

The STRINGREP procedure converts one or more elements to a string of 
characters, then returns that string and the length of the string. 

Use this format for the STRINGREP procedure call: 

STRINGREP(string_name, length, element {.element}...) 

string_name 

Name of a string type variable. (You can specify it as a substring.) The 
result is returned here. It will contain the character representations of 
the named elements). 

length 

Name of an integer variable. The procedure will set its value to the 
length in characters of the resulting string variable, string_name. It 
will be less than or equal to the declared length of the string variable. 

element 

Name of the element to be converted. The element can be a scalar, 
floating-point, pointer, or string type. Formats for specifying particular 
types and rules for conversion of those types are discussed in more 
detail later in this chapter. 

The named elements are converted to strings of characters. Those strings are 
then concatenated and returned left-justified in the named string variable. 
The length of the string variable is also returned. If the result of 
concatenating the string representations is longer than the length of the 
string variable, the result is truncated on the right; the length that will be 
returned is the length of the string variable. 

Each individual element is converted and placed in a temporary field before 
concatenation with other elements. The length of the temporary field can be 
specified as part of the element parameter that is described in the following 
sections. Generally, numeric values are written right-justified in the 
temporary field with spaces added on the left to fill the field, if necessary. 
String or character values are written left-justified in the temporary field 
with spaces added on the right to fill the field, if necessary. For both numeric 
and alphabetic values, the field is filled with asterisk characters if it is too 
short to hold the resulting value. The value of the field length, when 
specified, must be greater than or equal to zero; otherwise, an error occurs. 

The following paragraphs describe how the STRINGREP procedure converts 
specific types and how they appear in the temporary fields. 
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Integer Element 

Use this format to specify an integer element: 
expression {•' length } {•' U(radix )} 

expression 

An integer expression to be converted. 
length 

A positive integer expression specifying the length of the temporary 
field. The length must be greater than or equal to 2. If omitted, the 
temporary field is the minimum size required to hold the integer value 
and the leading sign character. 

radix 

Radix of expression. Possible values are 2, 8,10, and 16. If omitted, 10 
(decimal) is assumed. 

The value of the integer expression is converted into a string representation 
in the desired radix. The resulting string representation is right-justified in 
the temporary field. If the expression is positive, a space precedes the 
leftmost significant digit. If the integer expression is negative, a minus sign 
precedes the leftmost significant digit. The leading space or hyphen must be 
considered a part of the length. Thus, the length must be greater than or 
equal to 2 in order to hold the sign character and at least one digit. 

If you specify a field length larger than necessary, spaces are added on the 
left to fill the field. If you specify a field length that is not long enough to 
contain all digits and the sign character, the field is filled with a string of 
asterisk characters. If you specify a field length less than or equal to zero, an 
error occurs. 


Character Element 

Use this format to specify a character element: 
expression {•' length } 
expression 

A character expression to be converted. 
length 

A positive integer expression specifying the length of the temporary 
field. If omitted, a length of 1 is assumed. 

A single character is left-justified in the temporary field. If you specify a field 
length larger than necessary, spaces are added on the right to fill the field. 
Including a radix for a character element causes a compilation error. 


Revision A 


Procedures 7-3 



STRINGREP 


Boolean Element 

Use this format to specify a boolean element: 
expression {•' length } 
expression 

A boolean expression to be converted. 
length 

A positive integer expression specifying the length of the temporary 
field. If omitted, a length of 5 is assumed. 

Either of the 5-character strings ’ TRUE’ or ’FALSE’ is left-justified in the 
temporary field. If you specify a field length larger than necessary, spaces 
are added on the right to fill the field. If you specify a field length that is not 
long enough to contain all five characters, the temporary field is filled with 
asterisk characters. Including a radix for a boolean element causes a 
compilation error to occur. 


Ordinal Element 

The integer value of an ordinal expression is handled the same way as an 
integer element. Refer to the discussion under Integer Element earlier in this 
chapter. 


Subrange Element 

A subrange element is handled the same way as the element of which it is a 
subrange. 
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Floating-Point Element 

Use this format to specify a floating-point element: 
expression {•' length {•' fraction )} 

expression 

A real expression to be converted. If the value is INFINITE or 
INDEFINITE, an error occurs. 

length 

A positive integer expression specifying the length of the temporary 
field. If omitted, the temporary field is the minimum size required to 
hold the integer value and the necessary leading character. 

fraction 

Positive integer expression specifying the number of fractional digits 
to be included in a fixed-point format. Specify a value less than or 
equal to ’’length - 2”. If omitted, conversion to floating-point format is 
assumed. 

A floating-point expression can be converted into either a fixed-point format 
or a floating-point format depending on the fraction parameter. If it is 
included, the expression is converted to fixed-point format; if omitted, the 
expression is converted to floating-point format. 
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Fixed-Point Format 
The form 

expression {•' length {• fraction}} 

causes the specified expression to be converted to a string in fixed-point 
format. The string will have the specified length with the specified number of 
fractional digits to the right of the decimal place. The expression is rounded 
off so that the specified number of fractional digits are present. If no positive 
digit appears to the left of the decimal point, a 0 (zero) is inserted. 

When figuring the length required to hold the expression, the compiler counts 
all digits to the left of the decimal point (it also counts 0 if it appears alone), 
the decimal point, and the specified number of fractional digits that appear 
to the right of the decimal point. If the expression is negative, an extra space 
is required for the minus sign. If you specify a field length larger than 
necessary, spaces are added on the left to fill the field. If you specify a field 
length that is not long enough to contain all digits, the sign character, and 
the decimal point, the field is filled with a string of asterisk characters. 

Examples: 

Value of Expression E Format of Element Resulting String 


1.23456 

-1.23456 

0 


E:6:2 
E: 6:3 
E:5:2 
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Floating-Point Format 

The form 

expression {•' length } 

causes the specified expression to be converted to a string in floating-point 
format. 

The length of the temporary field is determined somewhat differently from 
the other elements. The system defines a maximum number of digits that 
can be contained in the mantissa of a real number and the number of digits 
that can be in the exponent. 

When the compiler figures the number of digits that will be in the mantissa, 
it first determines the number of spaces that must be present in the string. It 
allows for the number of digits in the exponent and four additional spaces: 
one for the sign of the expression (a space if positive, - if negative), one for 
the decimal point in the mantissa, one for the exponent character (E), and 
one for the sign of the exponent (+ or -). The total number of required spaces 
is subtracted from the specified field length. The compiler then compares the 
result (field length minus required spaces) and the maximum number of 
digits allowed in the mantissa, and takes the smaller of the two. That 
number is used as the number of digits in the mantissa when the compiler 
rounds the floating-point expression. 

If a field length larger than necessary is specified, spaces are added on the 
left to fill the field. If the fixed size of the exponent is larger than necessary, 
zeroes are added on the left to fill the field. If the number that results from 
the subtraction of required spaces from the field length is less than 1, the 
field is filled with a string of asterisk characters. 

Examples: 

Value of Expression E Format of Element Resulting String 

123.456 E: 10 ' 1.23E+002' 

-123.456 E:ll '-1.235E+002' 
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Pointer Element 

Use this format to specify a pointer element: 
pointer {•' length } {•' U(radix )} 

pointer 

A pointer reference to be converted. 
length 

A positive integer expression specifying the length of the temporary 
field. If you omit the field length, the temporary field is the minimum 
size required to contain the pointer value. 

radix 

Radix of the pointer value. Possible values are 2, 8,10, and 16. For 
NOS/VE, the default radix is 16. 

The value of the pointer expression is converted into a string representation 
in the specified radix. It is right-justified in the temporary field. If you specify 
a field length larger than necessary, spaces are added on the left to fill the 
field. If you specify a field length that is not long enough to contain all the 
digits, the field is filled with a string of asterisk characters. 

String Element 

Use this format to specify a string element: 
expression {•' length J 
expression 

A string variable, string constant, or substring to be converted. 
length 

A positive integer expression specifying the length of the temporary 
field. If omitted, the field is the minimum size required to contain the 
string expression. 

A string expression is left-justified in the temporary field. If you specify a 
field length larger than necessary, spaces are added on the right to fill the 
field. If you specify a field length that is shorter than the length of the string, 
the temporary field is filled with a string of asterisk characters. 
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User-Defined Procedures 


Procedure Declaration 

You define your own procedures with procedure declarations. 

Use this format to declare a procedure: 

PROCEDURE {/ attributes]} name {(formal-parameters )};t 
{declaration _list} 

{statement-list} 

PROCEND {name}; 

attributes 

Specify one or more of the following attributes. If you specify more 
than one attribute, separate them with commas. 

XREF 

The procedure has been compiled in a different module. In this case, 
the procedure declaration can contain the name and formal 
parameters, but no declaration list or statement list. In the other 
module, the procedure must have been declared with the XDCL 
attribute and an identical parameter list. If omitted, the procedure 
must be defined within the module where it is called. 

XDCL 

The procedure can be called from outside the module in which it is 
located. This attribute can be included only in a procedure declared 
at the outermost level of a module; it cannot be contained in a 
program, function, or another procedure. Other modules that call 
this procedure must contain the same procedure declaration with 
the XREF attribute specified. 


t Some variations of CYBIL available on other operating systems allow an 
additional option, the alias name, in a procedure declaration. If included in 
a CYBIL program run on NOS/VE, this parameter is ignored. 
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INLINE 

Instead of calling the procedure, the compiler inserts the actual 
procedure statements at the point in the code where the procedure 
call is made. 

#GATEt 

The procedure can be called by a procedure at a higher ring level if 
the call is issued from within the call bracket of the gated 
procedure.tt If you specify #GATE, you must also specify the XDCL 
attribute. 

If you don’t specify any attributes, the procedure is assumed to be in 
the same module in which it is called. 

name 

Name of the procedure. The procedure name is optional following 
PROCEND. 

formal parameters 

One or more parameters in the form: 

VAR name {.name}...- type 
[.name {.name}...: type}... 

and/or: 

name Iname}... : type 
Iname {.name}... ■' type}... 

The first form is called a reference parameter; its value can be changed 
during execution of the procedure. The second form is called a value 
parameter; its value cannot be changed by the procedure. Both kinds of 
parameters can appear in the formal parameter list; if so, separate 
them with semicolons (for example, I: INTEGER; VAR A: CHAR). 
Reference and value parameters are discussed in more detail later in 
this chapter under Parameter List. 

declaration _list 

Zero or more declarations. 

statement _list 

Zero or more statements. 


t This attribute is not supported on variations of CYBIL available on other 
operating systems. 

tt A ring level is a hardware feature. Rings provide hardware protection in 
that an unauthorized program cannot access anything at a lower ring 
level. For further information on rings, refer to the SCL Object Code 
Management manual. 
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pRocEDtnais 


A parameter list is an optional list of variable declarations that appears in 
the first statement of the procedure declaration. In the procedure declaration 
format shown earlier, they are shown as formal _parameters. Declarations 
for formal parameters must appear in that first statement; they cannot 
appear in the declaration list in the body of the procedure. 

A parameter list allows you to pass values from the calling program to the 
procedure. When a call is made to a procedure, parameters called actual 
parameters are included with the procedure name. The values of those actual 
parameters replace the formal parameters in the parameter list. Wherever 
the formal parameters exist in the statements within the procedure, the 
values of the corresponding actual parameters are substituted. For every 
formal parameter in a procedure declaration, there must be a corresponding 
actual parameter in the procedure call. 

There are two kinds of parameters: reference parameters and value 
parameters. A reference parameter has the form: 

VAR name {.name}... : type 
{.name {.name}... - type]... 

When a reference parameter is used, the formal parameter represents the 
corresponding actual parameter throughout execution of the procedure. Thus, 
an assignment to a formal parameter changes the variable that was passed 
as the corresponding actual parameter. An actual parameter corresponding 
to a formal reference parameter must be addressable. A formal reference 
parameter can be any fixed or adaptable type. If the formal parameter is a 
fixed type, the actual parameter must be a variable or substring of an 
equivalent type. If the formal parameter is an adaptable type, the actual 
parameter must be a variable or substring whose type is potentially 
equivalent. (For further information on potentially equivalent types, refer to 
Equivalent Types in chapter 4.) 
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A value parameter has the form: 

name [ ,name }...: type 
{,name {,name }... • type}... 

When a value parameter is used, the formal parameter takes on the value of 
the corresponding actual parameter. However, the procedure cannot change 
a value parameter by assigning a value to it or using it as an actual 
reference parameter to another procedure or function. A formal value 
parameter can be any fixed or adaptable type except a type that cannot have 
a value assigned, that is, a heap, or an array or record that contains a heap. 
If the formal parameter is a fixed type, the actual parameter can be any 
expression that could be assigned to a variable of that type. Strings must be 
of equal length. If the formal parameter is an adaptable type, the current 
type of the actual parameter must be one to which the formal parameter can 
adapt. If the formal parameter is an adaptable pointer, the actual parameter 
can be any pointer expression that could be assigned to the formal 
parameter. Both the value and the current type of the actual parameter are 
assigned to the formal parameter. 

Reference parameters and value parameters can be specified in many 
combinations. When both kinds of parameters appear together, they must be 
separated by semicolons. Parameters of the same type can also be separated 
by semicolons instead of commas, but in this case, VAR must appear with 
each reference parameter. All of the following parameter lists are valid: 

• VAR i, j: integer; a, b: char; 

• VAR i: integer; VAR j: integer; a: char; b: char; 

• a: char; VAR i, j: integer; b: char; 

• VAR i: integer, j: real; a: char, b: boolean; 

In each of the preceding examples, I and J are reference parameters; A and B 
are value parameters. 
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Calling a Procedure 

A call to a procedure consists of the procedure name (as given in the 
procedure declaration) and any parameters to be passed to the procedure in 
the following format: 

name {(actual_parameters)}; 

name 

Name of the procedure or a pointer to a procedure. 
actual parameters 

One or more expressions or variables to be substituted for formal 
parameters defined in the procedure declaration. If you specify two or 
more, separate them with commas. They are substituted one-for-one 
based on their position within the list; that is, the first actual 
parameter replaces the first formal parameter, the second actual 
parameter replaces the second formal parameter, and so on. For every 
formal parameter in a procedure declaration, there must be a 
corresponding actual parameter in the procedure call. 

A procedure is a type, like the types described in chapter 4. Procedure types 
are used for declaration of pointers to procedures; there are no procedure 
variables. 

The lifetime of a formal parameter is the lifetime of the procedure in which it 
is a part. Storage space for the parameter is allocated when the procedure is 
entered and released when the procedure is left. 

The lifetime of a variable that is allocated using the storage management 
statements (described in chapter 5) is the time between the allocation of 
storage (with the ALLOCATE statement) and the release of storage (with the 
FREE statement). 

Two procedure types are equivalent if corresponding parameter segments 
have the same number of formal parameters, the same methods of passing 
parameters (reference or value), and equivalent types. 
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Example: 

This example calculates the greatest common divisor X of M and N. M and N 
are passed as value parameters; that is, their values are used but M and N 
themselves are not changed. X, Y, and Z are reference parameters (preceded 
by the VAR keyword). Their original values are not used in this procedure; 
they are assigned new values in the procedure that destroy their previous 
values. 

PROCEDURE gcd (m, 
n: integer; 

VAR x, 

V, 

z: integer); 

■CExtended Euclid's Algorithm> 

VAR 

al/ 

a2, 

bl, 

b2, 

c, 

d, 
q, 

r: integer; 

al := 0; 
a2 := 1; 
bl := 1; 
b2 := 0; 
c := m; 
d := n; 

WHILE d <> 0 DO 

■Cal * m + bl * n = d, a2 * m + b2 * n = c> 

•Cgcd (c,d) = gcd (m,n)> 
q := c DIV d; 
r := c MOD d; 
a2 := a2 - q * al; 
b2 := b2 - q * bl; 
c := d; 
d := r; 
r := al; 
al := a2; 
a2 := r; 
r := bl; 
bl := b2; 
b2 := r; 

WHILEND; 



Cx = gcd (m/n), y*m + z*n = gcd (m,n)> 
PROCEND gcd; 
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System-Dependent Procedures 

Of the procedures described here, some can be used only with NOS/VE; 
others may be available in variations of CYBIL on other operating systems, 
but they are not guaranteed to be. Keep in mind that programs using these 
procedures may not be transportable to other systems. 

To use these procedures properly and efficiently, you should be familiar with 
basic hardware concepts of your computer system. This information can be 
found in volume II of the virtual state hardware reference manual. 

The functions are described in alphabetical order. 

#CALLER_ID Procedure 

The #CALLER_ID procedure returns the identification (caller id) of the 
caller of a function or procedure. This procedure can be used only with 
NOS/VE. 

Use this format for the #CALLER_ID procedure call: 
#CALLER_ID(id_record) 
id _record 

Name of the record that will contain the caller id information. It must 
be four bytes long. 

The caller id is a record that contains the global/local key, ring number, and 
segment number of the caller. When a function or procedure is called, the 
caller id is placed in the leftmost 32 bits of the XO register as a result of a call 
relative (CALLREL) or call indirect (CALLSEG) hardware instruction. The 
#CALLER_ID procedure accesses XO while this information is there. 

No special scope attributes (XDCL or XREF) are required in the calling 
function or procedure to use this procedure. 

For further information on the caller id record and the CALLREL and 
CALLSEG instructions, refer to volume II of the virtual state hardware 
reference manual. 
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Example: 

The following example sets the pointer variable PSA_PTR to point to the 
first cell of the previous save area. The #CALLER_ID procedure then returns 
information about the caller of the last function. That information is 
returned in the record CALLER_RECORD. In this example, CALLER, 
RECORD is equivalent to the object of pointer PSA_PTR (that is, CALLER, 
RECORD = PSA_PTR"). 

TYPE 

id_rec = record 
id: 0 .. Offffffff(16), 
recend; 

VAR 

psa_ptr: "id_rec, 
caller_record: id_rec; 

psa_ptr := #previous_save_area (); 

#caller_id (caller_record); 
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#COMPARE_SWAP Procedure 

The #COMPARE_SWAP procedure performs actions equivalent to the 
compare swap (CMPXA) hardware instruction. It compares the contents of a 
variable with an expression. If the variable is unlocked and equal to the 
expression, the variable is swapped with a new expression. This procedure 
can be used only with NOS/VE. 

Use this format for the #COMPARE_SWAP procedure call: 

#COMPARE_SWAP(lock_variable, initial, expression, 
new.expression, actual, variable, result .variable) 

lock.variable 

Name of the variable on which the compare swap operation is to be 
performed. This variable must be aligned on a word boundary. 

initial.expression 

Expression that is compared to the lock variable. They must be equal 
for the swap operation to occur. 

new _ expression 

Expression that specifies the value to be stored in the lock variable if 
the swap is successful (that is, the contents of lock_variable equals 
initial_expre8sion). 

actual, variable 

Name of the variable into which the initial contents of the lock 
variable is returned. If the lock variable is locked, this field is not 
changed. 

result, variable 

Name of the variable into which the result of the compare swap 
instruction is returned. Specify a subrange from 0 to 2 where each 
value has the following significance: 

0 

Swap operation was successful. 

1 

Swap operation failed because the initial expression was not equal 
to the contents of the lock variable. 

2 

Swap operation failed because the lock variable was locked. 

The types of the lock variable, initial expression, new expression, and actual 
variable must be equivalent and have a size of eight bytes. 
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The lock variable is said to be locked if the leftmost 32 bits are ones. If it is 
locked, no action occurs. If it is unlocked, the contents of the lock variable is 
assigned to the actual variable. Then the lock variable is compared to an 
initial expression. If they are equal, a new expression is assigned to the lock 
variable. Otherwise, no swap occurs. 

This procedure essentially performs the following statements: 

IF (left half of lock_variable) = 0ffffffff(16) THEN 
result_ variable := 2; 

ELSE 

actual _ variable := lock_variable; 

IF lock_variable = initial_expression THEN 
lock_variable := new_expression; 
result_variable := 0; 

ELSE 

result_variable := 1; 

IFEND; 

IFEND; 

These statements are executed by the hardware as a noninterruptable 
sequence. Access to the lock_variable from other sources, such as another 
processor or peripheral processor (PP), is prevented while these statements 
are being executed. 

For further information on the CMPXA instruction, refer to volume II of the 
virtual state hardware reference manual. 

Example: 

The following example compares the variable LOCK with INITIAL. If 
LOCK is unlocked and equal to INITIAL, the value of LOCK is replaced by 
the value of variable NEW. In this example, LOCK is unlocked and equal to 
INITIAL. Therefore, following completion of the procedure, LOCK is equal to 
NEW which is 10. The variable RESULT is 0 indicating that the swap was 
successful. 

VAR 

lock, 

initial, 

new, 

actual: integer, 
result: 0 .. 2; 

lock := 5; 
initial := 5; 
new := 10; 

#compare_swap (lock, initial, new, actual, result); 
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#CONVERT_POINTER_TO_PROCEDURE 

Procedure 

The #CONVERT_POINTER_TO_PROCEDURE procedure converts a 
variable of the type pointer to procedure that has no parameters to a variable 
of the type pointer to procedure that can have parameters. This procedure 
may not be available on variations of C YBIL that execute on other operating 
systems. 

Use this format for the #CONVERT_POINTER_TO_PROCEDURE 
procedure call: 

#CONVERT_POINTER_TO_PROCEDURE(pointer_ 1, pointer_2) 
pointer_ 1 

Name of a pointer to procedure variable with no parameters. 

pointer_2 

Name of a pointer to procedure variable with an arbitrary parameter 
list. 

Example: 

The following example converts the variable PTR_TO_PROCl, a pointer to 
a procedure that has no parameters, to the variable PTR_TO_PROC2, a 
pointer to a procedure that does have parameters. 

VAR 

ptr_to_proc1: "procedure, 
ptr_to_proc2: "procedure (argl: integer, 
arg2: real); 

ptr_to_proc1 := “procl; 

#convert_pointer_to_procedure (ptr_to_proc1, ptr_to_proc2); 
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#HASH_SVA Procedure 

The #HASH_SVA procedure performs actions equivalent to the load page 
table index (LPAGE) hardware instruction. This instruction searches the 
system page table (SPT) for a given system virtual address (SVA). This 
procedure can be used only with NOS/VE. 

Use this format for the #HASH_SVA procedure call: 

#HASH_SVA(sva_variable, index, count, result_variable) 

sva_ variable 

Name of the variable that contains the SVA for which the instruction 
will search. 

index 

Name of an integer variable that will contain a word index into the 
SPT. If the SVA is found, this index points to the SPT entry for the 
SVA. If the SVA is not found, it points to the last entry searched. 

count 

Name of an integer variable that will contain the number of SPT 
entries searched. 

result_variable 

Name of a boolean variable that is set to TRUE if the SVA is found. 

The procedure returns either an index within the table if the SVA is found, or 
an index of the last entry searched if the SVA is not found. It also returns 
the number of entries searched and a boolean value indicating whether the 
entry was found. 

For further information on the SVA, addressing in general, and the LPAGE 
instruction, refer to volume II of the virtual state hardware reference manual. 
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#KEYPOWT 


#KEYPOINT Procedure 

The #KEYPOINT procedure generates an inline keypoint hardware 
instruction based on parameters supplied in the call. It allows performance 
monitoring of programs using keypoint instructions as trap interrupts. This 
procedure can be used only with NOS/VE. 

Use this format for the #KE YPOINT procedure call: 

#KEYPOINT(class, data, identifier) 

class 

A constant integer expession from 0 to 15 that specifies the keypoint 
class. This value is placed in the j field of the hardware instruction. 

data 

A constant or variable expression from 0 to OFFFFFFPF hexadecimal 
that specifies optional data to be collected with the keypoint. If you 
specify the constant 0, a 0 is placed in the k field of the hardware 
instruction. If you don’t specify 0, the value is placed in an X register 
and that register is placed in the k field of the hardware instruction. 

identifier 

A constant expression from 0 to OFFFF hexadecimal that specifies a 
keypoint identifier. It is placed in the Q field of the hardware 
instruction. 

For further information on the KEYPOINT instruction, refer to volume II of 
the virtual state hardware reference manual. 
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#PURGE_BUFFER Procedure 

The #PURGE_BUFFER procedure performs actions equivalent to the purge 
hardware instruction. It purges the contents of cache or the map buffer. This 
procedure can be used only with NOS/VE. However, not all computer 
systems that support NOS/VE have cache and map buffers. If executed on a 
model without cache or map buffers, no action occurs. 

Use this format for the #PURGE_BUFFER procedure call: 

#PURGE_BUFFER(option_value, address) 

option _ value 

A constant integer expression from 0 to 15 that specifies one of the 
following purge options: 

0 

Purge all entries in cache that are included in the 512-byte block 
defined by the system virtual address (SVA) in Xj. 

1 

Purge all entries in cache that are included in the active segment 
identifier (ASID) defined by the SVA in Xj. 

2 

Purge all entries in cache. 

3 

Purge all entries in cache that are included in the 512-byte block 
defined by the process virtual address (PVA) in Xj. 

4-7 

Purge all entries in cache that are included in the segment number 
defined by the PVA in Xj. 

8 

Purge all entries in the map (page table map if entries are kept in 
separate maps) relating to the page table entry defined by the SVA 
in Xj. 
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#PURGE _ BUFFER 


9 

Purge all entries in the map (page table map if entries are kept in 
separate maps) relating to the page table entries that are included in 
the segment defined by the SVA in Xj. 

10 or A(16) 

Purge all entries in the map (page table map if entries are kept in 
separate maps) relating to the page table entry defined by the PVA 
in Xj. 

11 or B(16) 

Purge all entries in the map (both the page table and segment map) 
relating to the segment table entry defined by the PVA in Xj, and to 
all page table entries included within that segment. 

12-15 or C(16)-F(16) 

Purge all entries in the map. 

address 

Name of a 6-byte variable that specifies the PVA or SVA of the data to 
be purged. 

For further information on addressing, cache and map buffers, and the purge 
instruction, refer to volume II of the virtual state hardware reference manual. 

Example: 

The following example purges all entries in cache that are in the block 
defined by the PVA in pointer variable PTR1. 

VAR 

i: integer, 
ptrl: "cell; 

ptrl := "i; 

#purge_buffer (3, ptrl); 
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#SCAN Procedure 

The #SCAN procedure scans a string from left to right until one of a 
specified set of characters is found or the entire string has been searched. 
This procedure may not be available on variations of C YBIL that execute on 
other operating systems. 

Use this format for the #SCAN procedure call: 

#SCAN(scan_variable, string, index, result_ variable) 

scan_variable 

Name of the variable that indicates the character values for which the 
string is scanned. The variable must be 256 bits long. Each bit of the 
variable represents the character in the corresponding position of the 
ASCII character set. If a bit is set, the corresponding character is one 
for which the procedure scans. 

string 

String or substring to be scanned, 
index 

Name of an integer variable. If a character is found during scanning, 
the index of that character is returned in this variable. The index of a 
character is that character’s position in the string; for example, the 
index value of the first character is 1. If no matching values are found, 
the variable contains the string length plus one. 

result_variable 

Name of a boolean variable, which is set to TRUE if the scan finds one 
of the selected characters. 

The procedure looks for any one character from a set of characters specified 
in a 256-bit variable. Bits are set in the variable to correspond to the 
characters in the same positions in the ASCII character set collating 
sequence. A set bit indicates that the procedure scans the string for the 
corresponding character. The procedure stops if it finds one of the characters 
specified. It returns the position of the character that caused termination and 
the boolean variable that indicates whether a character was found. 
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#SCAN 


Example: 

The following example searches the string variable SOURCE_STRING for 
the asterisk character (*). First, the character to be searched for (the asterisk) 
must be specified in the array variable SELECT. To do this, all 256 elements 
of SELECT are set to 0. Then the $INTEGER function is used to determine 
the position of the asterisk character in the ASCII character set collating 
sequence. The value returned in I is 42 (because the asterisk is in the forty- 
second position in the collating sequence). The forty-second position in the 
array SELECT is then set to 1. Assuming SOURCE_STRING contains an 
asterisk as the fifty-fourth character of the string, the value returned in 
INDEX is 54 and the value returned in RESULT is TRUE. 

VAR 

source_string: string (100), 

select: packed array CO .. 255] of 0 .. 1, 

i/ 

index: integer, 
result: boolean; 

FOR i := 0 TO 255 DO 
select Ci] := 0; 

FOREND; 

i := {INTEGER ('*'); 

select CiD := 1; 

#scan (select, source_string, index, result); 
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#TRANSLATE Procedure 

The #TRANSLATE procedure translates each character in a source field 
according to a translation table, and transfers the result to a destination 
field. This procedure may not be available on variations of CYBIL that 
execute on other operating systems. 

Use this format for the #TRANSLATE procedure call: 

#TRANSLATE(table, source, destination) 

table 

Name of a string variable whose length is 256 characters. This 
variable defines the translation table. 

source 

String to be translated, 
destination 

Name of a string variable into which the translated string is 
transferred. 

Translation of the string occurs from left to right with each source byte used 
as an index into the translation table. TYanslated bytes from the table are 
stored in the destination field. 

If the length of the source field is less than the length of the destination field, 
translated spaces fill the destination field. If the source field is larger than 
the destination field, the rightmost characters of the source field are 
truncated. 

Example: 

The following example translates a string named SOURCE_STRING 
according to an externally referenced translation table named TRANS1_ 
TABLE. The resulting string is placed in DEST_STRING. 

VAR 

trans1_table: CXREF3 string (256), 
source_string: string (100), 
dest_string: string (100); 

source_string (1, 10) := 'ten chars.'; 

translate (trans1_table, source_string, dest_string); 
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#UNCHECKED_CONVERSION 

#UNCHECKED_CONVERSION Procedure 

The #UNCHECKED_CONVERSION procedure copies directly from a 
source field to a destination field. This procedure may not be available on 
variations of CYBIL that execute on other operating systems. 

Use this format for the #UNCHECKED_ CONVERSION procedure call: 

#UNCHECKED_CONVERSION(source, destination) 

source 

Name of a variable from which the copy is made, 
destination 

Name of a variable to which the copy is made. 

The source and destination fields must have the same length in bits. Neither 
the source nor the destination field can be a pointer or contain a pointer. If 
either the source or destination field is the object of a pointer reference 
(pointer*), the pointer cannot be a pointer to a procedure. 

Hie destination field must satisfy the same restrictions as the target of an 
assignment statement. This means that the destination field cannot be: 

• A read-only variable. 

• A formal value parameter of the procedure that calls the 
#UNCHECKED_CONVERSION procedure. 

• A bound variant record. 

• The tag field name of a bound variant record. 

• A heap. 

• An array or record that contains a heap. 

Example: 

Hie following example copies the contents of a 5-character string named 
SOURCE to a 5-element array named DESTINATION. After the operation, 
the contents of both variables are identical. 

VAR 

source: string (5), 

destination: packed array Cl .. 5D of char; 
#unchecked_conversion (source, destination); 
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#WRITE_REGISTER Procedure 

The #WRITE_REGISTER procedure performs actions equivalent to the copy 
to state register (CPYXS) hardware instruction. It allows a program to 
change the contents of a process or processor register. This procedure can be 
used only with NOS/VE. 

Use this format for the #WRITE_REGISTER procedure call: 

#WRITE _ REGISTE R(r egister _ id, data) 
register_id 

An integer expression from 0 to 255 that identifies the number of the 
register to be written. Register numbers are given in volume II of the 
virtual state hardware reference manual. 

data 

Integer expression that contains the data to be written to the register. 

The #READ_REGISTER function described in chapter 6 allows a program 
to read the contents of a process or processor register. 

Writing to certain registers requires special privileges. For further 
information on process and processor registers, and the CPYXS instruction, 
refer to volume II of the virtual state hardware reference manual. 

Example: 

The following example changes the contents of register E5, the Debug mask 
register, to IF hexadecimal. 

VAR 

i: integer; 
i := Olf(16); 

#write_register (oe5(16), i); 
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This chapter describes the CYBIL command, the FORMAT_CYBIL_ 
SOURCE command, and the declarations, statements, and directives that 
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The CYBIL Command and 
Other Compilation Facilities 


$ 


This chapter describes the CYBIL command, the FORMAT CYBIL_ 
SOURCE command, and the declarations, statements, and directives that 
can be used at compilation time. The CYBIL command is used to compile one 
or more CYBIL modules. The FORMAT_CYBIL_SOURCE command is 
used to reformat CYBIL source code The compilation statements and 
directives are used to construct the unit to be compiled and to control that 
process. If a CYBIL command and a directive specify conflicting options, the 
option encountered most recently is used. 

For further information on program execution, refer to the SCL Object Code 
Management manual. 

The CYBIL and FORMATCYBILSOURCE commands described next are 
standard system commands and use the syntax and language elements for 
parameters described in the SCL Language Definition manual. 


CYBIL Command 

Purpose The CYBIL command calls the compiler, specifies the files to 
be used for input and output, and indicates the type of output 
to be produced. 

Format CYBIL 

INPUT=file 

LIST=fHe 

BINARY-file 

LIST_OPTIONS=list of keyword value 
DEBUG _AIDS=list of keyword value 
ERROR _LEVEL=keyword value 
OPTIMIZATION_LEVEL=key word value 
PAD=integer 

RUNTIME_CHECKS=list of keyword value 
STATUS=status variable 

Pinmrtws INPUT or I 

Specifies the file that contains the source text to be read. You 
can specify a file position as part of the file name. Source 
input ends when an end-of-partition or an end-of-information 
is encountered on the source input file. If omitted, $INPUT is 

assumed. 


LIST or L 

Specifies the file on which the compilation listing is to be 
written. You can specify a file position as part of the file 
name. If you specify $NULL, all compile-time output is 
discarded. If omitted, $LIST is assumed. 
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CYBIL COMMAND 


BINARY or B or BINARY_OBJECT or BO 
Specifies the file on which object code is to be written. You can 
specify a file position as part of the file name. If you specify 
$NULL, the compiler performs a syntactic and semantic scan 
of the program but does not generate object code. If omitted, 
$LOCAL.LGO is assumed. 

LIST _OPTIONS or LO 

Specifies a combination of the following list options. If you 
specify NONE, no list options are selected. If omitted, option S 
(list the source input file) is assumed. 

A 

Produces an attribute list of source input block structure 
and relative stack. The attribute listing is produced 
following the source listing on the file specified by the 
LIST parameter or, if you omit the LIST parameter, on file 
$LIST. 

F 

Produces a full listing. In effect, this option selects options 
A, S, and R. 

O 

Lists compiler-generated object code. When selected, this 
listing includes an assembly-like listing of the generated 
object code. This option has no effect if the BINARY_ 
OBJECT parameter is set to $NULL. 

R 

Produces a symbolic cross-reference listing showing the 
location of a program entity definition and its use within a 
program. 

RA 

Produces a symbolic cross-reference listing of all program 
entities whether referenced or not. 

S 

Lists the source input file. 

X 

Used in conjunction with the compile-time directive 
LISTEXT so that listings can be externally controlled 
using the CYBIL command. The LISTEXT toggle must be 
ON. For further information, refer to Toggle Control under 
Compile-Time Directives later in this chapter. 
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CYBIL COMMAND 


DEBUG_AIDS or DA 

Specifies a combination of the following debug options. If 
omitted, NONE (no debug options) is assumed. 

ALL 

Selects debug options DS and DT. 

DS 

Compiles all debugging statements. A debugging 
statement is a statement in the source text that is ignored 
unless this option is specified. These statements are 
enclosed by the compile-time directives COMPILE and 
NOCOMPILE. (For further information, refer to 
Maintenance Control under Compile-Time Directives later 
in this chapter.) The symbol table and line table for 
interactive debugging are also generated. 

DT 

Generates debug tables (that is, the symbol table and line 
table) as part of the object code. These tables are used by 
the Debug utility. 

NONE 

No debug options are selected. 

ERROR_LEVEL or EL 

Specifies one of the following error list options. If omitted, W 
(list warning and fatal diagnostics) is assumed. 

F 

lists fatal diagnostics. If selected, only fatal diagnostics 
are listed. 

W 

Lists warning (informative) diagnostics as well as fatal 
diagnostics. 
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OPTIMIZATION_LEVEL or OL or OPTIMIZATION or OPT 

Specifies one of the following optimization options. If omitted, 
LOW is assumed. 

DEBUG 

Object code is stylized to facilitate debugging. Stylized code 
contains a separate packet of instructions for each 
executable source statement; it carries no variable values 
across statement boundaries in registers, and it notifies 
Debug each time the beginning of a statement or procedure 
is reached. 

LOW 

Provides for keeping constant values in registers. 

HIGH 

Provides for keeping local variables in registers, passing 
parameters to local procedures in registers, and 
eliminating redundant memory references, common 
subexpressions, and jumps to jumps. 

PAD 

Generates the specified number of no-op (no operation) 
instructions between instructions that actually perform 
operations. If omitted, zero is assumed; no-op instructions are 
not generated. 
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CYBIL COMMAND 


R UNTIME _ CHECKS or RC 

Specifies a combination of the following run-time checking 
options. If omitted, NONE (no run-time checks) is assumed. 

ALL 

Selects run-time checking options N, R, and S. 

N 

Produces compiler-generated code that checks for a NIL 
value when a reference is made to the object of a pointer. 

NONE 

No run-time checks are produced. 

R 

Produces compiler-generated code to check ranges. Range 
checking code is generated for assignment to integer 
subranges, ordinal subranges, and character variables. All 
CASE statements are checked to ensure that the selection 
expression corresponds to one of the variant values 
specified if no ELSE clause is provided. All references to 
substrings are verified. If you specify an offset (variable 
pointer) on a RESET statement, it is checked to ensure that 
it is valid for the specified sequence. 

S 

Produces compiler-generated code to test the subscripting 
of arrays. 

STATUS 

Specifies an optional SCL status variable in which the 
completion status of the command is returned. If specified, the 
compiler returns a status to this variable indicating whether 
any fatal errors were found during the compilation that was 
just completed. You can test this status variable and take 
special action if fatal compilation errors occurred. If omitted 
and the status returned from the compiler is abnormal, SCL 
terminates the current command sequence. 
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CYBIL COMMAND 


Remarks If the compiler command specifies an option that differs from 

a directive, the latest occurrence of either the command or the 
directive takes precedence. 

Example This command reads source code from a file named 

COMPILE, writes the compilation file on file LIST, and writes 
the object code on file BIN1. The listing includes source code, 
compiler-generated object code, and a symbolic cross-reference 
listing. 

cybil i=conipUe l=List b=bin1 lo=(o,r) 
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FORMAT_CYBIL_SOURCE COMMAND 

FORMAT_CYBIL_SOURCE Command 

Purpose Reformats CYBIL source code for consistency and greater 

readability. 

Format FORMAT CYBIL SOURCE or 

FORCS 

INPUT=file 
OUTPUT=file 
STATUS=status variable 

Parameters INPUT or / 

Specifies the file from which the CYBIL source code is to be 
read. If omitted, local file I is assumed. 

OUTPUT or O 

Specifies the file on which the reformatted CYBIL source code 
is to be written. If omitted, local file O is assumed. 

STATUS 

Specifies an optional SCL status variable in which the 
completion status of the command is returned. 

Remarks The CYBIL source code must be syntactically correct. 

Example This command reformats the CYBIL source program 

contained on file INITIAL and writes it to file 
$USER.FINAL. 

format_cybil_source initial $user.final 
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COMPILE-TIME VARIABLES 


Compilation Declarations and 
Statements 

Many program elements defined in CYBIL have counterparts that can be 
used to control the compilation process. They include variable declarations, 
expressions, and the assignment and IF statements. The IF statement is 
used to specify certain areas of code to be compiled. The IF statement 
requires the use of expressions, which in turn require variables. Assignment 
statements are used to change the value of variables and, thus, expressions. 


Compile-Time Variables 

Only boolean type variables can be declared. 

Use this format to specify a boolean type compile-time variable: 

? VAR name {.name}... '• BOOLEAN := expression 

{, name {.name}...: BOOLEAN■= expression}... ?; 

name 

Name of the compile-time variable. This name must be unique among 
all other names in the program. 

expression 

A compile-time expression that specifies the initial value of the 
variable. 

A compile-time declaration must appear before any compile-time variables 
are used. The scope of such a variable extends from the point at which it is 
declared to the end of the module. Compile-time variables can be used only in 
compile-time expressions and compile-time assignment statements. 
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Compile-Time Expressions 

Compile-time expressions are composed of operands and operators like 
CYBIL-defined expressions. An operand can be: 

• Either of the constants TRUE or FALSE. 

• A compile-time variable. 

• Another compile-time expression. 

The operators are NOT, AND, OR, and XOR Heir order of evaluation from 
highest to lowest is: 

• NOT 

• AND 

• OR and XOR 

'these operators have their usual meanings, as described under Operators in 
chapter 5. 
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Compile-Time Assignment Statement 

A compile-time assignment statement assigns a value to a compile-time 
variable. 

Use this format for the compile-time assignment statement: 

? name := expression ?; 
name 

Name of a compile-time variable, 
expression 

A compile-time expression. 
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Compile-Time IF Statement 

The compile-time IF statement compiles or skips a certain area of code 
depending on whether a given expression is true or false. 

Use this format for the compile-time EF statement: 

? IF expression THEN 
code 
{ ?ELSE 
code} 

? I FEND 

expression 

A boolean compile-time expression, 

code 

An area of CYBIL code or text 

When the expression is evaluated as true, the code following the reserved 
word THEN is compiled. When compilation of that code is completed, 
c ompilation continues with the first statement following IFEND. When the 
expression is false, compilation continues following the ELSE phrase, if it is 
included, or following IFEND. 

The ELSE clause is optional. If included, the ELSE clause designates an 
area of code that is compiled when the preceding expression is false. 

Example: 

The following example shows the declaration of a compile-time variable 
named SMALL SIZE that is initialized to the value TRUE. A line of CYBIL 
code declaring an array named TABLE is compiled. Then a compile-time IF 
statement checks the value of SMALL_SIZE. If it is TRUE, the line of 
CYBIL code calling a procedure named BUBBLESORT is compiled in the 
program. If it is FALSE, the CYBIL line calling procedure QUICKSORT is 
inserted instead. Because SMALL_SIZE was initialized to TRUE, the call to 
BUBBLESORT is included in the compiled program. 


?VAR 

saall.size: boolean := TRUE?; 

VAR 

table: array Cl .. 503 of integer; 

?IF saall_size = TRUE THEN 
bubblesort (table); 

?ELSE 

quicksort (table); 

? 

IFEND 
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COMPILE-TIME DIRECTIVES 


Compile-Time Directives 

Compile-time directives allow you to perform the following activities during 
compilation: 

• Set toggles that turn on or off listing options such as source code listing 
and object code listing (SET, PUSH, POP, and RESET directives when 
they contain one or more of the listing options). 

• Set toggles that turn on or off run-time options such as range checking 
and array subscript checking (SET, PUSH, POP, and RESET directives 
when they contain one or more of the run-time checking options). 

• Specify the layout of the source text to be used (LEFT and RIGHT margin 
directives). 

• Specify the layout of the resulting listing (EJECT, SPACING, SKIP, 
NEWTITLE, TITLE, and OLDTITLE directives). 

• Specify what code to compile (COMPILE and NOCOMPILE directives). 

• Include comments in the object module (COMMENT directive). 

You can specify one or more directives with the format: 

?? directive {, directive }... ?? 
directive 

One of the directives discussed in the remainder of this chapter. They 
can be broken down into four categories: 

• Toggle control (SET, PUSH, POP, and RESET) 

• Layout control (LEFT, RIGHT, EJECT, SPACING, SKIP, 
NEWTITLE, TITLE, and OLDTITLE) 

• Maintenance control (COMPILE and NOCOMPILE) 

• Object code comment control (COMMENT) 

Directives must be bounded by a pair of consecutive question marks. These 
delimiters are not shown in the following formats for individual directives, 
but they are required around one or more directives. 

If a directive differs from an option specified on a compiler command, the 
latest occurrence of either the directive or the command takes precedence. 
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SET 


Toggle Control 

Toggle controls can set the values of individual toggles, save and restore 
preceding toggle values in a last in-first out manner, and reset all toggles to 
their initial values. 


SET Directive 

The SET directive specifies the setting of one or more toggles. 

Use this format for the SET directive: 

SET (togglename := condition {.toggle_name := condition}...) 
toggle _ name 

Name of the toggle being set listing toggles are described in table 8-1. 
Run-time checking toggles are described in table 8-2. The names of 
toggles can be used freely outside of directives. 

condition 

ON or OFF. If a toggle is ON, the activity associated with it is 
performed during compilation; if it is OFF, the activity is not 
performed. 

AH settings specified in the SET directive are done at the same time. If the 
directive list contains more than one setting for a single toggle, the rightmost 
setting in the list is used. 
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LISTING TOGGLES 


Table 8-1 describes the listing toggles and gives their initial settings. 


Table 8-1. Listing Toggles 


Toggle 

Initial 

Value 

Description 

LIST 

ON 

Determines whether other listing toggles are read. 
When ON, a source listing is produced and the 
other listing toggles are used to control other 
aspects of listing. When OFF, no listing is 
produced; the other listing toggles are ignored. 

USTOBJ 

OFF 

Controls the listing of generated object code. 

When ON, object code is interspersed with source 
code following the corresponding source code line. 

LISTCTS 

OFF 

Controls the listing of the listing toggle directives 
and layout directives. 

LISTEXT 

OFF 

When ON, the listing of source statements is 
controlled by a list option on the CYBIL compiler 
command. 

USTALL 

Not 

applicable 

This option represents all of the listing toggles. 
When ON, all other listing toggles are ON; when 
OFF, all other listing toggles are OFF. 
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RUN-TIME CHECKING TOGGLES 


Table 8-2 describes the run-time checking toggles and gives their initial 
settings. 


Table 8-2. Run-Time Checking Toggles 


Toggle 

Initial 

Value 

Description 

CHKRNG 

ON 

Controls the generation of object code that 
performs range checking of scalar subrange 
assignments and case variables. 

CHKSUB 

ON 

Controls the generation of object code that checks 
array subscripts (indexes) and substring 
selections to verify that they are valid. 

CHKNIL 

OFF 

Controls the generation of object code that checks 
for a NIL value when a reference is made to the 
object of a pointer. 

CHKALL 

Not 

applicable 

This option represents all run-time checking 
toggles. When ON, all other run-time checking 
toggles are ON; when OFF, all other run-time 
checking toggles are OFF. 
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PUSH 


PUSH Directive 

The PUSH directive specifies the setting of one or more toggles like the SET 
directive, but before the settings are put into effect, a record of the current 
state of all toggles is saved for later use. 

Use this format for the PUSH directive: 

PUSH (toggle_name := condition {,toggle_name := condition}...) 

toggle _ name 

Name of the toggle being set. Listing toggles are described in table 8-1. 
Run-time checking toggles are described in table 8-2. The names of 
toggles can be used freely outside of directives. 

condition 

ON or OFF. If a toggle is ON, the activity associated with it is 
performed during compilation; if it is OFF, the activity is not 
performed. 

Settings in the PUSH list are performed in the same manner as a SET list. If 
the directive list contains more than one setting for a single toggle, the 
rightmost setting in the list is used. 

The POP directive, described later in this chapter, restores the original toggle 
settings in a last in-first out manner (that is, the last record to be saved is the 
first to be restored). 

Example: 

This example turns off listing temporarily, that is, until the POP directive is 
encountered. 

?? PUSH (LIST := OFF) ?? 

?? POP ?? 
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POP Directive 

The POP directive restores the last toggle settings that were saved by the 
PUSH directive. 

Use this format for the POP directive: 

POP 

If no record was kept (such as when a SET directive is performed), the initial 
settings are restored. 

Example: 

This example shows a PUSH directive that temporarily turns off listing. The 
POP directive restores listing. 

?? PUSH (LIST := OFF) ?? 

?? POP ?? 
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RESET 


RESET Directive 

The RESET directive restores the initial toggle settings. 

Use this format for the RESET directive: 

RESET 

When the RESET directive is performed, any record of previous settings is 
destroyed. 
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LEFT AND RIGHT 


Layout Control 

Layout controls are used to specify the margins of the source text and to 
control the layout of the listing. 

LEFT and RIGHT Directives 

The LEFT and RIGHT directives specify the column number of the left and 
right margins of the source text, respectively. 

Use these formats for the LEFT and RIGHT directives: 

LEFT := integer 

RIGHT := integer 

integer 

An integer value that represents the column number of the left and 
right margins, respectively. 

The left margin must be greater than zero; that is: 
left margin > 0 

The right margin must be greater than or equal to the left margin plus 
10, and less than or equal to 110; that is: 

left margin + 10 <= right margin <= 110 

All source text left of the left margin and right of the right margin is ignored. 

If you don’t use the margin directives, the left margin is assumed to begin in 
column 1 with die right margin in column 79. 

Example: 

This example sets the left margin at column 1 and the right margin at 

column 110. 

?? LEFT := 1, RIGHT := 110 ?? 
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EJECT Directive 

The EJECT directive causes the paper to be advanced to the top of the next 
page. 

Use this format for the EJECT directive: 

EJECT 
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SPACING Directive 

The SPACING directive specifies the number of blank lines between 
individual lines of the listing. 

Use this format for the SPACING directive: 

SPACING := spacing 
spacing 

One of the values 1, 2, or 3 specifying single, double, and triple spacing, 
respectively. 

An undefined value has no effect on spacing, but an error message is issued. 

If you don’t use the SPACING directive, single spacing (no intervening 
blank lines) is assumed. 
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SKIP 


SKIP Directive 

The SKIP directive specifies that a given number of lines is to be skipped. 

Use this format for the SKIP directive: 

SKIP := lines 
lines 

Integer value specifying the number of lines to skip. Specify a value 
greater than or equal to 1. 

If you specify more lines than the number of lines on the page, or if you 
specify a value for lines that would cause the paper to skip past the bottom of 
the current page, the paper is advanced to the top of the next page. 
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NEWTITLE Directive 

The NEWTITLE directive specifies a new, additional title to be used on a 
page while saving the current title. 

Use this format for the NEWTITLE directive: 

NEWTITLE := ’character_string’ 

character _ string 

A character string specifying the title to be used. A single quote mark 
is indicated by two consecutive quote marks enclosed by quote marks 
[that is, ””]. 

The current title is saved and the given character string becomes the current 
title. A standard page header is always the first title printed on a page, 
followed by user-defined titles in the order in which they were saved. This 
means that titles are saved and restored in a last in-first out order, but they 
are printed in a first in-first out order. There is always a single empty line 
between the standard page header and any user-defined titles. There is 
always at least one empty line between the last title and the text. 

Hk maximum number of titles that can be specified is 10. Any attempts to 
add more titles is ignored. 

Tiding does not take effect until the top of the next printed page. 
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TITLE 


TITLE Directive 

The TITLE directive replaces the current user-defined title with the given 
character string. 

Use this format for the TITLE directive: 

TITLE := ’character_string’ 
character _ string 

A character string specifying the title to be used. A single quote mark 
is indicated by two consecutive quote marks enclosed by quote marks 
[that is, ””]. 

If there is no user-defined title currently, the character string becomes the 
current title. 

A standard page header is always the first title printed on a page. There is 
always a single empty line between the standard page header and any user- 
defined titles. There is always at least one empty line between the last title 
and the text. 

Titling does not take effect until the top of the next printed page. 
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OLDTITLE Directive 

The OLDTITLE directive restores the last user-defined title that was saved, 
making it the current title. 

Use this format for the OLDTITLE directive: 

OLDTITLE 

If there is no saved title, no action occurs. 
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COMPILE 


Maintenance Control 


COMPILE Directive 

The COMPILE directive causes compilation to occur, or to resume after the 
occurrence of a NOCOMPILE directive. 

Use this format for the COMPILE directive: 

COMPILE 

If you don’t use either the COMPILE nor NOCOMPILE directive, the 
COMPILE directive is assumed; source code is compiled. 

When the CYBIL command includes the DEBUG_AIDS parameter with DS 
specified, debugging statements enclosed by the COMPILE and 
NOCOMPILE directives are compiled. 
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NOCOMPILE Directive 

The NOCOMPILE directive causes compilation to stop until the occurrence 
of a COMPILE directive or the end of the module. 

Use this format for the NOCOMPILE directive: 

NOCOMPILE 

NOCOMPILE continues listing source code and text according to the listing 
toggles and layout directives, interpreting and obeying directives, but source 
code is not compiled until a COMPILE directive is encountered or a 
MODEND statement is encountered. 

When the CYBIL command includes the DEBUG_ AIDS parameter with DS 
specified, debugging statements enclosed by the COMPILE and 
NOCOMPILE directives are compiled. 


Revision D 


CYBIL Command/Other Facilities 


8-27 



COMMENT 


pr 


Comment Control 
COMMENT Directive 

The COMMENT directive causes the compiler to include the given character 
string in the commentary portion of the object module generated by the 
compilation process. 

Use this format for the COMMENT directive: 

COMMENT := ’character _ string’ 
character _ string 

A character string of up to 40 characters that specifies a compile-time 
comment. 

This directive allows you to include comments in object modules so that the 
comments appear in the load maps. Any number of comments can be 
included, but only the last comment encountered appears. 

Example: 

?? COMMENT := 'Copyright 1985 by Control Data Corporation' ?? 
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This chapter describes the Debug utility, which aids in debugging CYBIL 

programs. 
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Introduction 

The Debug utility provides source code level symbolic debugging for 
programs written in BASIC, COBOL, CYBIL, FORTRAN, and PASCAL, 
and machine code level debugging for object modules. Using Debug does not 
require source-level program modifications, a knowledge of assembly 
language, or the ability to interpret extensive memory dumps. Debugging 
can be done at the source language level. 

Debug enables you to monitor and control the execution of programs in 
interactive and batch mode. Debug allows program conditions to be modified 
and tested during execution. With Debug, you can: 

• Suspend program execution at specified locations, such as line 398 of 
module MAI N PROGRAM. 

• Suspend program execution when a selected event occurs, such as writing 
to a specified location. 

• Display and change the values of program variables, memory locations, 
and registers while execution is suspended. 

• Display the procedure calls that led to the current location (call traceback 
information). 

• Display the environment that you are currently debugging under. 

• Resume program execution at the location where execution was 
suspended or at another location. 

• Step through a program by lines or procedures. 
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ACCESSING DEBUG 


Because Debug is a command utility, SCL features are available while 

Debug is in control. With SCL, you can: 

• Temporarily read Debug subcommands from a file other than the Debag 
input file using the SCL command INCLUDE_F1LE. 

• Enter multiple commands, separated by semicolons, on one line. 

• Continue a single command on one or more continuation lines. 

• Evaluate and display SCL expressions using the SCL command 
DISPLAY.. VALUE. 

• Echo Debug subcommands to one or more files, and write Debug output to 
several files using the SCL command CREATE_FILE_CONNECTION. 

• Include Debug subcommands in SCL procedures. 

• Enter commands for processing by another active command processor, 
such as an editor to examine your source listing. 


Accessing Debug 

You can access Debug explicitly when executing your program. You can also 
access Debug when your program aborts unexpectedly. 
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Accessing Debug During Program Execution 

Every program has various attributes that control its execution. Among 
these are the Debug attributes DEBUG_MODE, DEBUG_INPUT, and 
DEBUG_OUTPUT. These attributes are defined as follows: 

DEBUG_MODE = ON or OFF 

A keyword value that determines whether or not the program is to be 
executed under Debug control. 

DEBUG_INPUT = file 

The file from which Debug initially reads subcommands when 
DEBUG_MODE=ON. 

DEBUG_OUTPUT = file 

The file to which Debug initially writes its output. 

These attributes can be specified at two levels'- program level and job level. 
Program level specifications apply to a specific program. Job level 
specifications apply to all programs of a job that do not explicitly specify 
values at the program level. 

Program level specifications are set as parameter values on the SCL 
command EXECUTE _TASK or on the SCL CREATE _OBJECT, LIBRARY 
utility’s subcommand CREATE_PROGRAM_DESCRIPTION. Job level 
specifications are set as parameter values of the SCL command SET_ 
PROGRAM_ATTRIBUTE. (Refer to the SCL Object Code Management 
manual for complete descriptions of these commands.) 

For example, if you issue 

set_program_attributes debug_mode=on 

just after logging in, all program executions will be under control of Debug 
unless you specify DEBUG_MODE=OFF on the EXECUTE _TASK 
command or in a previously created program description. You can change 
job level attributes at any time by issuing another SET_PROGRAM_ 
ATTRIBUTES command. 

Initially, the values of the job level Debug attributes are DEBUG _ 
MODE=OFF, DEBUG_INPUT=COMMAND, and DEBUG, 
OUTPUT=$OUTPUT. For interactive jobs, COMMAND and $OUTPUT are 
assigned to the terminal by default. 

Individual sites and individual users at a site can change these initial 
defaults by including a SET_PROGRAM_ATTRIBUTES command in the 
system or user prologue file. 
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Accessing Debug When Program Failure Occurs 

Once you have a working program, you generally want to access Debug only 
if the program unexpectedly fails. The program attributes that control Debug 
when a working program fails are ABORT_FILE and DEBUG_OUTPUT. 
These attributes are defined as follows: 

ABORT_FILE = file 

The file from which Debug initially reads subcommands if the program 
aborts when DEBUG_MODE=OFF. 

DEBUG_OUTPUT = file 

The file to which Debug initially writes its output. 

These attributes can be specified at two levels: program level and job level. 
Program level specifications apply to a specific program. Job level 
specifications apply to all programs of a job that do not explicitly specify 
values at the program level. 

Program level specifications are set as parameter values on the SCL 
command EXECUTE _TASK or on the SCL CREATE_OBJECT_LIBRARY 
utility’s subcommand CREATE_PROGRAM_DESCRIPTION. Job level 
specifications are set as parameter values of the SCL command SET_ 
PROGRAM_ ATTRIBUTE. (Refer to the SCL Object Code Management 
manual for complete descriptions of these SCL commands.) 

For example, if you issue 

set_program_attributes debug_mode=off / abort_file=abortfiLe 

just after logging in, Debug will not gain control unless the program fails. 
Programs will not execute under the control of Debug unless you specify 
DEBUG_MODE=ON on the EXECUTE _TASK command or in a previously 
created program description. You can change job level attributes at any time 
by issuing another SET_PROGRAM_ ATTRIBUTES command. 

The initial value of ABORT_FILE is $NULL, the special system file with no 
data in it. DEBUG_MODE must be off and ABORT_FILE must be a file 
other than $NULL for Debug to gain control when the program fails. 
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Debug Concepts 

This section contains miscellaneous information that applies to Debug 
usage. This information includes Debug input/output, status variable, 
breaks, and addressing. 


Debug Input/Output 

Although Debug input/output takes place automatically, you can, by 
manipulating the Debug input/output files, expand the capabilities of 
Debug. 


Debug Input 

Debug subcommands are initially read from the file specified by the 
DEBUG_INPUT parameter or the ABORT_FILE parameter of the SCL 
commands EXECUTE _TASK, CREATE _PROGRAM _ DESCRIPTION, or 
SET _ PROGRAM _ ATTRIBUTE S. 

The default Debug input file is COMMAND. In interactive jobs, COMMAND 
is the terminal. In batch jobs, it is the normal command stream. You cannot 
use COMMAND as the source of Debug input for a batch job because 
COMMAND is positioned at beginning-of-information, which is your 
LOGIN command. Instead, you must copy the Debug input to another file, 
using the SCL command COLLECT_TEXT for example, and use that as the 
Debug input. 

You can change the input file temporarily by entering an SCL INCLUDE_ 
FILE command. As soon as you enter the command, subcommands are read 
from the specified file until an end-of-partition, an end-of-information, or a 
RUN subcommand is encountered. If an end-of-partition or an end-of-file is 
encountered, subcommands are again read from the file that contained the 
INCLUDE _FILE command. If a RUN subcommand is encountered, 
program execution is resumed; any remaining subcommands in the file that 
was included are not processed. When Debug again gains control, 
subcommands are read from the current Debug input file. 
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The Debug subcommand CHANGE _ DEFAULT (described in detail later in 
this chapter) can also be used to change the Debug subcommand source. The 
DEBUG_INPUT parameter of the CHANGE_DEFAULT subcommand 
changes the subcommand source so that Debug subcommands are read from 
the specified file when Debug gains control after program execution has 
been resumed. Unlike the INCLUDE_FILE command, the CHANGE_ 
DEFAULT subcommand has no effect on the current subcommand source. 

If Debug is activated from within an SCL procedure, subcommands are read 
from COMMAND when Debug gains control, not from the procedure. To 
force Debug to read subcommands from the procedure, specify 

debug_input=$command 

in the program description or on the EXECUTE _TASK command. 


Debug Output 

Debug output (messages and information produced by Debug display 
subcommands) is initially written to the file specified by the DEBUG_ 
OUTPUT parameter (default output file is $OUTPUT) of the SCL 
commands EXECUTE_TASK, CREATE_PROGRAM_DESCRIPTION, or 
SET _ PROGRAM _ ATTRIBUTES. The OUTPUT parameter of the Debug 
display subcommands can be used to divert display output to another file; 
the diversion applies only to the subcommand that contains the OUTPUT 
parameter. 

The Debug subcommand CHANGE_DEFAULT (described in detail later in 
this chapter) can be used to change the current Debug output file. The 
DEBUG_OUTPUT parameter of the CHANGE_DEFAULT subcommand 
causes Debug to write sill output to the specified file; the change takes place 
as soon as the subcommand is executed. 

The default Debug output file is $OUTPUT. $OUTPUT is the terminal for 
interactive jobs and the listing file for batch jobs. Initially, IOUTPUT is 
connected to the actual file OUTPUT. You can connect $OUTPUT to other 
files by using the SCL command CREATE _ FILE _ CONNECTION. If the 
standard files $ECHO, $RESPONSE, and $ERRORS are also connected to 
one of the actual output files, a complete record of a Debug session can be 
created. 
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Status Variable 

All Debug subcommands have an optional parameter called STATUS. When 
you specify this parameter, a previously declared SCL variable of kind 
STATUS must be supplied as its value. (Refer to the SCL Language 
Definition manual for a discussion of SCL variables.) This variable contains 
the completion status of the subcommand. 

A status variable is a record that contains the following fields: 

NORMAL 

A boolean that has a value of FALSE if the subcommand could not be 
processed correctly and a value of TRUE if the subcommand was 
processed correctly. 

IDENTIFIER 

A string with a length of 2 that contains the product identifier of the 
processor in which the error was detected. The product identifier for 
Debug is DB. This field is undefined when the subcommand is processed 
correctly. 

CONDITION 

An integer code that identifies the detected error. The two leftmost digits 
in a Debug condition code are 64. This field is undefined when the 
subcommand is processed correctly. 

TEXT 

A string with a length of 256 that contains the error message text. This 
field is undefined when the subcommand is processed correctly. 

The presence of the STATUS parameter on a subcommand causes the next 
subcommand to be processed even if an error condition is encountered. After 
checking the contents of the status variable, you can use succeeding 
subcommands to alter the flow of control based upon the occurrence of error 
conditions. 
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Breaks 


The primary mechanism that allows Debug to gain control from an 
executing program is the user-defined break. A user-defined break specifies 
one or more events and an address range so that when a specified event 
occurs within the address range, program execution is interrupted and Debug 
takes control. 

Many events can be specified, for example, when execution reaches a specific 
place, before a branch to a specific address range occurs, or before a write 
into memory. Address ranges also can be specified in many forms. You 
cannot set two breaks for the same event at the same address range or 
overlapping address ranges. Once set, a break stays set until it is explicitly 
deleted or implicitly deleted with the DELETE _BREAK ALL subcommand. 
The SET_BREAK, DELETE _BREAK, and DISPLAY_BREAK 
subcommands are used to set, delete, and display break definitions. (These 
subcommands are described in detail later in this chapter.) 

The maximum number of breaks that the Debug utility can handle is 64. Of 
these 64 breaks, 32 can be the type of break that is detected by Debug 
hardware (read, write, call, branch, execution, and read next instruction). 
Some breaks that you set cause Debug to set one or more internal breaks. 
Thus, the actual maximum number of breaks that are available to you is not 
a fixed number. A message is issued when another break cannot be set. 


Addressing 

Debug uses source level addresses when addresses are reported in Debug 
subcommand output, such as when DISPLAY_CALL or DISPLAY_BREAK 
is executed and when Debug gains control. Debug also uses source level 
addresses when addresses are referenced in Debug subcommands, such as 
SET_BREAK and DISPLAY_MEMORY. 
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Reported Addresses 

The level of reported addresses is determined by the information available. 
For CYBIL programs, the following are available by default: 

• Module address tables indicating where modules are located. 

• Line address tables indicating where code for each line is located. 

• Symbol tables indicating where the value of each program name is 
located. 

If you specify DEBUG_AIDS=NONE on the CYBIL command, however, line 
address and symbol table addresses are suppressed. In this case, only module 
and machine level addressing are possible. 

Addresses in the message issued when Debug gains control (the break report 
message) are formatted as follows depending on the information available. 

When line and module tables are available (symbolic addressing): 

If the address corresponds to the beginning of a line, then the format is 

M=module _name L=line_number 

otherwise, if the address is somewhere within the line, then the format is 

M=module_name L=line_number B0=byte _ offset _ from _ 
start _ of _ line 

When only the module table is available (module addressing): 

If the module is not bound (refer to Addressing Bound Modules later in 
this chapter), then the format is 

M=source_ module _ name P=procedure_name BO=byte_ 
offset _ from _ start _ of _ procedure 

otherwise, if the module is bound, then the format is 

M=source_module name BO=byte_offset_from_ 
start_of_bound_module 

When line and module tables are not available (machine addressing), the 
format is: 

A=machine _ address 
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Within the address formats: 

• module_name and procedure_name correspond to the source program 
module and procedure names. 

• line_number corresponds to a line number on the source listing. 

• byte _ offset is a decimal number corresponding to the number of bytes 
beyond the beginning of a line or a hexadecimal number corresponding to 
the number of bytes beyond the start of a procedure or bound module. 

• machine _ address is a set of three hexadecimal numbers representing the 
ring number, segment number, and segment offset of a machine address. 

Addresses reported in subcommand output also provide the highest address 
level possible, but they are not always formatted the same as in break report 
messages. Addresses shown in DISPLAY_BREAK output are very similar, 
but addresses shown in DISPLAY_CALL output contain both the procedure 
name and line number. Typical DISPLAY,CAT.I, output might look like 
this: 


— Traceback from procedure PR0C2 module M0D2 at line 34 

— Called from procedure PR0C1 module M0D2 at line 55 byte 
offset 4 

— Called from procedure BEGIN_PROCESS module MODI byte 
offset 1A3C16) 

Addresses shown in DISPLAY_REGISTER output are formatted only as 
hexadecimal addresses in the form 

r sss oooooooo 

where r is the ring number, sss is the segment number, and oooooooo 
is the offset from the start of the segment. Pointer addresses displayed by 
DISPLAY_PROGRAM_VALUE are also formatted as hexadecimal 
machine addresses except for pointers to procedures; dereferenced pointers to 
procedures are displayed as the procedure name if possible. 
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Referenced Addresses 

Several Debug subcommands reference program code and data addresses. 
For example, SET_BREAK designates an address or address range for 
break events, DISPLAY_MEMORY specifies the address of memory to be 
displayed, and DISPLAY_PROGRAM_VALUE names a program identifier 
whose value is to be displayed. 

Just as for reporting addresses, the capabilities available when referencing 
program addresses depend on the information available: 

• Symbolic addressing (source level addressing) is available if line and 
symbol tables exist (they exist unless line number and symbol table 
generation is specifically turned off at compile time). 

• Module/procedure offset addressing is available if module tables exist 
(they always do for user programs). 

• Machine-level addressing is always available. 

Addresses can be referenced in many more forms than the form in which 
they are reported. For example, entry point names, section names, and 
program names can be referenced, but addresses are never reported in these 
terms. Machine level addresses can be referenced only as a single integer (a 
12-digit hexadecimal value); they are reported, however, either as a 12-digit 
hexadecimal integer or as three separate integers corresponding to ring 
number, segment number, and byte offset from the start of the segment. 
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Not all address forms, however, are used by all subcommands. For example, 
the DISPLAY_PROGRAM_VALUE subcommand allows a program name 
to be referenced by name, including all of the subscripting and qualification 
syntax. But, the DISPLAY_PROGRAM_VALUE subcommand does not 
allow machine level addressing. The DISPLAY_MEMORY subcommand, on 
the other hand, allows machine and module addressing but almost no 
symbolic level addressing. The SET _ BREAK subcommand allows all forms 
except names defined in a source program. 

The different forms of addresses are specified by different parameters. LINE, 
MODULE, PROCEDURE, NAME, ENTRY_POINT, SECTION, and 
ADDRESS are typical address parameter names. Many of these address 
parameters can be used in combination to specify an address. For example, 
LINE and MODULE together specify a particular line of a particular 
module. NAME, MODULE, and PROCEDURE together specify a particular 
name of a particular procedure in a particular module. Similarly, SECTION 
can be used in conjunction with MODULE. ENTRY_POINT and 
ADDRESS, however, cannot be used in conjunction with MODULE or with 
each other because they specify addresses independent of any module. Debug 
issues an error message if an invalid combination of address parameters is 
used. 

The BYTE _ OFFSET parameter can be used to modify the address 
parameters. For example, the MODULE parameter without the BYTE_ 
OFFSET parameter specifies the first byte of the module; the MODULE 
parameter modified with BYTE_OFFSET=4, on the other hand, specifies the 
fifth byte of the module. 

Another parameter, BYTE_COUNT, can be used to establish the block size 
(address range) associated with a referenced address. The BYTE _ COUNT 
parameter indicates how many memory bytes are to be included in the block. 
For example, 

section^rap, byte_count=3 

identifies a three-byte block that begins at section TRAP. BYTE_COUNT 
and BYTE _ OFFSET can be used to modify any referenced address except a 
program name (NAME parameter). 
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Addressing Bound Modules 

Individual modules can be bound (combined) to form a new load module that 
loads and executes faster than the original separate modules. (For further 
information, refer to the CREATE _OBJECT_ LIBRARY command in the 
SCL Object Code Management manual.) Binding modules together has no 
effect on address reporting or address referencing at the symbolic level; you 
can debug bound modules in terms of their component module names, line 
numbers, and identifier names. 

Binding does, however, have an effect on module/procedure and 
module/section offset addressing. After binding, original module and 
procedure names are not available when the tables that support symbolic 
addressing are not available; addresses sure reported and must be referenced 
in terms of the new bound module name and byte offsets from the beginning 
of the module. Code from all original component modules is combined into 
one code section, static data from all original modules are combined into one 
static data memory section, and so forth, so that the original component 
portions of each section cannot be distinguished by Debug. You can deduce 
where each component portion is by inspecting the section map produced by 
the GENERATE LIBRARY subcommand (described in the SCL Object 
Code Management manual). 


Debugging Optimized Code 

Most compilers can generate more than one level of object code. The 
OPTIMIZATION_LEVEL parameter on the compiler call controls the level 
of object code optimization. Specifying the DEBUG option on the 
OPITMIZATION_LEVEL parameter generates the most debuggable object 
code possible. This level of object code contains a separate packet of machine 
instructions for each executable source statement, carries no altered variable 
values across statement boundaries in registers without also updating their 
values in memory, enables Debug to recognize that start of execution of each 
new line or procedure, and ensures that Debug can always find actual 
parameter lists. 

If some higher level of optimization is selected, Debug can still function, but 
with restricted capabilities. For example, you cannot display program 
identifier values that are permanently allocated to machine registers. When 
values are temporarily carried in registers between statements, or when code 
for several source statements is mixed together, displayed values may not be 
the most recent values. Break report locations may not be as precise either. 
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Debugging With Condition Handlers 

Condition handlers are special procedures whose purpose is to process 
conditions, or exceptions, when they arise. They are automatically activated 
by NOS/VE when the conditions for which they have been established 
occur. Condition handlers can be established for one or more classes of 
conditions. Refer to the CYBIL System Interface manual for a detailed 
discussion of how to write condition handlers. 

When executing with DEBUG_MODE=ON, Debug first gains control when 
any condition occurs, except job resource conditions, detected uncorrected 
error conditions, and block exit conditions. The condition handler of the 
program, if one exists, is not executed until a Debug RUN subcommand is 
executed. 

The condition handler of the program can be debugged using Debug, but the 
program will not execute until you have had a chance to respond to the 
condition. For conditions for which breaks can be set, a RUN subcommand 
can be associated with the break so that the subcommand is automatically 
executed when the break occurs. (Refer to the COMMAND parameter of the 
SET_BREAK subcommand described later in this chapter.) This mechanism 
makes it possible to effectively circumvent the preemptive control of Debug. 

It appears as though Debug did not get control since the RUN subcommand 
automatically executes the instant the condition arises. 


Multitask Debugging 

The use of Debug in a multitask environment is very restricted. If an initial 
task executes with DEBUG_MODE=ON and then spins off a second task, 
the second task may execute with DEBUG _ MODE = ON (if its program 
description says to). This causes two separate instances of Debug to be 
active. The user may have difficulty distinguishing between them, as well as 
determining to which task a terminal is connected. One way to determine 
which instance of Debug has control is to inspect the output from the 
DISPLAY_CALL calling chain or from the user address displayed by 
DISPLAY_DEBUGGING_ENVIRONMENT. 

Interrupt Processing While Debugging 

Three external events can interrupt an executing user program or the Debug 
utility. These events are pause break, terminate break, and nearly exhausted 
resource. Table 9-1 shows the effects of these interrupts. 


9-14 CYBIL Language Definition 


Revision C 




DEBUG CONCEPTS 


Table 9-1. Effects of Interrupts While Debugging 


Interrupt 

User Program Executing 

Debug Executing 

Pause 

Break 

Debug gains control and 
prompts for subcommands. 

Default system action 
occurs. If you have 
established a handler for 
this condition, that 
handler gains control. 
Debug does not gain 
control unless the 
handler returns with 
normal status. 

Terminate 

Break 

Debug gains control and 
prompts for subcommands. 

If a Debug subcommand 
is executing, that 
subcommand is 
terminated and you are 
prompted for a new 
subcommand. If Debug 
is already waiting for a 
subcommand, the 
terminate break is 
ignored. 

Nearly 

Exhausted 

Resource 

Debug does not get control. 

If you have defined a handler, 
it gains control; otherwise, 
the system default handler 
processes the condition. 

Debug does not process 
this condition. If you 
have defined a handler, 
it gains control; otherwise, 
the system default 
handler processes the 
condition. Debug does 
not gain control unless a 
user-defined handler 
returns with normal 
status. 
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Debug Ring 

Debug normally runs in the same ring as the program being debugged. You 
can, however, control the ring in which Debug executes. The SCL command 
SET_DEBUG_RING specifies the ring in which Debug executes. The Debug 
ring cannot be set to a ring more privileged than the lowest ring for which 
you are validated. 

You are responsible for ensuring that the program being executed runs in the 
same ring set for Debug on the SET_DEBUG_RING command. (The ring 
attributes of the program can be changed using the SCL CHANGE _FILE_ 
ATTRIBUTES command.) 

If your program runs entirely in one ring, you need not be concerned with the 
Debug ring except to understand deferred breaks and multiple breaks (as 
discussed later in this section). 

If the program being debugged begins execution in a ring other than the 
Debug ring, Debug does not gain immediate control and the DB/ prompt 
does not appear. However, while the program is executing, you can access 
Debug by entering the user break 2 (termination) sequence (usually 
CONTROL/T followed by a carriage return) and then entering Debug 
subcommands. For example, you could interrupt the program soon after it 
begins execution and set breakpoints. 


Deferred Breaks 

Breaks that occur in a lower numbered ring than the Debug ring are 
deferred, or delayed, until execution again reaches the Debug ring. The break 
is deferred so that you do not get control in a ring more privileged than your 
own. If you were able to get control at a lower ring, you could read or change 
data that you normally do not have access to, thereby compromising system 
security. 

Deferred breaks can occur even when your program runs in a single ring. 
Many of the operating system services used by the program execute in more 
privileged rings. For example, if you set a read or write break on a status 
variable used in some NOS/VE request and that variable is accessed in a 
lower ring, the break is delayed until NOS/VE returns control to your 
program. 

When a break is deferred, Debug issues a special break report message. The 
break is reported as having happened at the line after the line that made the 
call, and a second line indicating the actual address of the event is output. 
The second line is formatted as follows: 

Trap deferred from <address> 

where address is where the event actually occurred. 
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Multiple Breaks 

Because breaks below the Debug ring are deferred until control returns to the 
Debug ring, several breaks can be stacked up before Debug gains control. 
When this happens, Debug must process multiple breaks. 

If there are several unprocessed breaks outstanding when Debug gains 
control, Debug reports each one in the usual way but honors only the first 
one that occurs. No subcommands are processed for the most recent breaks, 
not even subcommands associated with the break definition, since execution 
of the subcommands could destroy the environment that existed when the 
first break occurred. 

Multiple breaks can also occur when execution is not below the Debug ring. 
For example, two terminal breaks or an execution break and a terminal 
break could occur before Debug gets control. If this ever occurs, Debug 
honors only the first break. 


Multiring Environment 

The ability of Debug to function in a multiring environment is limited. If a 
break event occurs in a lower ring than the Debug ring, Debug gains control, 
but your options are limited. You can only resume execution of the 
interrupted procedure or terminate the Debug session. Any program 
condition handlers established for that event are not processed. 
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Debug Subcommands 


This section includes descriptions of the Debug subcommands. The 
subcommands are listed in alphabetical order. They follow the syntax and 
conventions for SCL commands, as described in the SCL Language 
Definition manual. The language elements used as parameters are standard 
SCL elements as defined in that manual, except for source program names 
used in the CHANGE_PROGRAM_VALUE and DISPLAY_PROGRAM_ 
VALUE subcommands. 


The Debug subcommands are summarized next. 

Subcommand_Description 


CHANGE .DEFAULT or 
CHANGE DEFAULTS or 
CHAD 

MODULE = name or keyword value 
PROCEDURE = name or keyword value 
DEBUG JNPUT = file 
DEBUG -OUTPUT = file 
STATUS = status variable 


Changes the default 
Debug input/output 
files and procedure 
and module names. 


CHANGE. MEMORY or Changes the 

CHAM contents of 

ADDRESS = integer memory. 

VALUE = string or integer 
TYPE = keyword value 

REPEAT-COUNT = integer or keyword value 
STATUS = status variable 


CHANGE.PROGRAM.VALUE or Changes the value 

CHAPV of a program 

NAME = name variable. 

VALUE = name 

MODULE = name 

PROCEDURE = name 

RECURSION _LEVEL = integer 

RECURSION-DIRECTION = keyword value 

STATUS = status variable 


(Continued) 
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(Continued) 

Subcommand 


CHANGE_REGISTER or 
CHANGE _ REGISTERS or 
CHAR 

KIND = keyword value 

NUMBER = keyword value or list of integer 

VALUE = integer or string 

TYPE = keyword value 

STATUS = status variable 

DELETE _ BREAK or 
DELETEBREAKS or 
DELB 

BREAK = keyword value or list of name 
STATUS = status variable 

DISPLAYBREAK or 
DISPLAY _BREAKS or 
DISB 

BREAK - keyword value or list of name 
OUTPUT = file 
STATUS = status variable 

DISPLAY CALL or 
DISPLAY_CALLS or 
DISC 

COUNT = integer or keyword value 

START = integer 

DISPLAY_OPTION = list of keyword value 
OUTPUT=file 
STATUS = status variable 
DISPLAY.DEBUGGING ENVIRONMENT or 

DISDE 

DISPLAY_OPTION = list of keyword value 

OUTPUT = file 
STATUS — status variable 


Description _ 

Changes the 
contents of the 
P, A, or X registers. 


Deletes one or more 
break definitions. 


Displays specified 
break definitions. 


Displays 

information about 
the dynamic call 
chain. 


Displays the 
debugging 
environment 
of your session. 


(Continued) 
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(Continued) 

Subcommand 


DISPLAY_MEMORY or 
DISM 
address 

BYTE _OFFSET = integer 
BYTE_COUNT = integer 
REPEAT_COUNT = integer or keyword value 
OUTPUT = file 
STATUS = status variable 

DISPLAY_PROGRAM_VALUE or 
DISPV 

NAME = program name or keyword value 

MODULE = name 

PROCEDURE - name 

RECURSION _LEVEL = integer 

RECURSION_ DIRECTION = keyword value 

TYPE = keyword value 

OUTPUT = file 

STATUS = status variable 

DISPLAY REGISTER or 
DISPLAY REGISTERS or 
DISR 

KIND = list of keyword value 

NUMBER = keyword value or list of integer 

TYPE = keyword value 

OUTPUT = file 

STATUS = status variable 

DISPLAY_STACK_FRAME or 
DISPLAY _ STACK _ FRAM E S or 
DISSF 

COUNT = integer or keyword value 
START - integer 

DISPLAY _OPTION = list of keyword value 
OUTPUT = file 
STATUS = status variable 


Description _ 

Displays the 
contents of memory. 


Displays the value 
of a program 
value. 


Displays the 
contents of 
the P, A, or 
X registers. 


Displays the 
contents of one or 
more stack frames. 


(Continued) 
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(Continued) 

Subcommand 


QUIT or 
QUI 

STATUS = status variable 

RUN 

STATUS = status variable 

SET_BREAK or 
SET_BREAKS or 
SETS 

BREAK = name 

EVENT = list of keyword value 

address 

BYTE ^OFFSET= integer 
BYTE COUNT integer 
COMMAND - string 
STATUS - status variable 

SET_STEP_MODE or 
SETSM 

MODE = keyword value 

UNIT = keyword value 

MODULE = keyword value or list of name 

PROCEDURE = keyword value or list of name 

SPAN = integer 

COMMAND = string 

STATUS = status variable 


Description _ 

Terminates the 
Debug session. 

Initiates or resumes 
program execution. 

Defines the break. 


Defines a subset of a 
task to be executed 
in one step. 
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CHANGE_DEFAULT 

Purpose Changes the default module, default procedure, default Debug 
input file, and default Debug output file. The change remains 
in effect until altered by another CHANGE-DEFAULT 
subcommand. 

Format CHANGE .DEFAULT or 

CHANGE-DEFAULTS or 
CHAD 

MODULE=name or keyword value 
PROCEDURE-name or keyword value 
DEBUG _INPUT = file 
DEBUG _OUTPUT = file 
STATUS = status variable 

Parameters MOD ULE or M 

Name of the module to be used if the module parameter is not 
specified in Debug subcommands that must refer to a module. 
Specifying the keyword $CURRENT causes the default 
module to be reset to the module that was executing when 
Debug gained control. 

Omission causes the current default module to remain 
unchanged. 

Debug subcommands that can use this default module are: 

CHANGE_PROGRAM_ VALUE 
DISPLAY-PROGRAM-VALUE 
SET-BREAK 
SET_STEP-MODE 

PROCEDURE or P 

Name of the procedure to be used if the procedure parameter is 
not specified in Debug subcommands that must refer to a 
procedure. Specifying the keyword $CURRENT causes the 
default procedure to be reset to the procedure that was 
executing when Debug gained control. 

Omission causes the current default procedure to remain 
unchanged. 

Debug subcommands that can use this default procedure are: 

CHANGE-PROGRAM-VALUE 

DISPLAY-PROGRAM-VALUE 

SET-BREAK 

SET-STEP-MODE 
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DEBUG _INPUT or DI 

File from which Debug subcommands are read when Debug 
next gains control. Unless you specify a file position as part of 
the file name, the file is initially positioned at the beginning- 
of-information; the file is not repositioned in subsequent 
accesses. Subcommands are read from the file sequentially. If 
an end-of-partition or an end-of-file is reached on the input 
file, program execution resumes. 

Omission causes the current Debug input file to remain 
unchanged. Unless specified otherwise, the initial Debug 
input file is COMMAND. 

DEBUG_OUTPUT or DO 

File on which Debug output is written. The change takes 
effect immediately. Break report messages and subcommand 
output are written to this file. Unless you specify a file 
position as part of the file name, the file is initially positioned 
at the beginning-of-information; the file is repositioned to the 
beginning-of-information in subsequent accesses. 

Omission causes the current Debug output file to remain 
unchanged. Unless specified otherwise, the initial Debug 
output file is $OUTPUT. 

STATUS 

Optional SCL status variable in which the completion status 
of the subcommand is returned. If omitted and an error does 
not occur, Debug processes the next subcommand. If omitted 
and an error occurs, the status value is returned to 
{RESPONSE and to the Debug output file if {RESPONSE is 
connected to that file. This file is normally connected during 
interactive debugging. 
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Examples The following subcommand specifies that Debug is to read 
subcommands from the file DBIN the next time Debug gains 
control: 

change_default debug_input=dbin 

The following subcommand specifies that Debug is to write its 
output to the file $LIST: 

change_default debug_output=$list 

The following subcommand specifies the default module 
name-' 

change_default module=main 
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CHANGE_MEMORY 


Purpose Changes the contents of memory starting at a specific 

address. You can change the value of any memory location for 
which you have write permission. 

Format CHANGE.MEMORY or 

CHAM 

ADDRESS = integer 
VALUE = string or integer 
TYPE - keyword value 

REPEAT_COUNT = integer or keyword value 
STATUS = status variable 

Parameters ADDRESS or A 

Address of the first byte of memory to be changed in the form 
188800000000 ( 16 ) 

where r is the ring number, sss is the segment number, and 
oooooooo is the offset from the beginning of the segment. You 
can obtain machine addresses by using the cross-reference 
and load maps for your program. 

This parameter is required. 

VALUE or V 

New memory value. A string value can be interpreted as a 
hexadecimal or ASCII string, depending on the value of the 
TYPE parameter. 

A hexadecimal string consists of the hexadecimal digits 0 
through 9 and A through F and spaces. Spaces are ignored, 
but you can use them to improve legibility. Each hexadecimal 
digit corresponds to 4 bits of memory. The first two digits 
replace the first byte of memory at the specified address, the 
second two digits replace the second byte, and so on. If there 
is an odd number of hexadecimal digits, only the first half of 
the corresponding byte is changed. 

An ASCII string consists of a string of ASCII characters. 

Each ASCII character corresponds to one byte of memory. 

The first character replaces the first byte of memory at the 
specified address, the second character replaces the second 
byte, and so on. 

An integer value completely replaces the contents of eight 
bytes. A diagnostic message is issued if the integer does not fit 
into eight bytes. 

This parameter is required. 
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TYPE or T 

Type of data defined by the VALUE parameter. Specify one of 
the following keywords: 

ASCII (A) 

VALUE is an ASCII string. 

HEX (H) 

VALUE is a hexadecimal string. 

INTEGER (I) 

VALUE is an integer. 

Omission causes HEX to be used for string values and 
INTEGER to be used for numeric values. 

REPEAT_COUNT or RC 

Number of times VALUE is repeated in memory. Specify a 
positive integer greater than zero. The address is incremented 
by the value size each time the value is repeated. The memory 
change is limited to the end of the data segment containing 
the specified address. Specifying a value that is too large or 
specifying the keyword ALL changes all the memory that can 
be changed. 

Omission causes 1 to be used. 

STATUS 

Optional SCL status variable in which the completion status 
of the subcommand is returned. If omitted and an error does 
not occur, Debug processes the next subcommand. If omitted 
and an error occurs, the status value is returned to 
$RESPONSE and to the Debug output file if $RESPONSE is 
connected to that file. This file is normally connected during 
interactive debugging. 

If the CHANGE _MEMORY subcommand contains an error 
before the STATUS parameter, the remainder of the 
subcommand is skipped. Therefore, the contents of the 
STATUS parameter does not reflect the status of the 
subcommand. 
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Examples The following subcommand replaces four bytes of memory 
beginning at location OB02200001112 hexadecimal with the 
hexadecimal string ’lOlOaaab’: 

changejnemory address=0b02200001112(16) .. 
vaLue='1010aaab' 

The following subcommand replaces six bytes of memory 
beginning at location OB02200000055 hexadecimal with the 
ASCII string ’string’: 

changejnemory address=0b02200000055(16) .. 
value='string' type=ascii 

The following subcommand replaces eight bytes of memory 
beginning at location 0B02300O00223 hexadecimal with the 
integer value 44: 

changejnemory address=0b02300000223(16) .. 
value=44 
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CHANGE_PROGRAM__ VALUE 

Purpose Changes the value of the specified program variable. 

Replacement values are entered in the same format as defined 
in your program, not as they are represented in memory. 

Format CHANGE_PROGRAM_VALUE or 

CHAPV 

NAME = name 
VALUE = name 

MODULE = name 
PROCEDURE = name 
RECURSION _LEVEL = integer 
RECURSION_DIRECTION= keyword value 
STATUS = status variable 

Parameters NAME or N 

Name of the program variable in the source program whose 
value is to be changed. Specify one of the following: 

• Simple variable name 

• Subscripted name 

• Field reference 

• Pointer dereference 

Subscripts can be constants or variables, but not expressions. 
Substring references are not allowed. 

Because names can be long, you can use SCL string variables 
as aliases for them. To do this, assign a string that contains 
the identifier to the SCL variable. Then use the SCL variable 
preceded by a question mark as the value of the NAME 
parameter. 

This parameter is required. 
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VALUE or V 

New value for the NAME parameter variable. The named 
VALUE parameter variable must be of the same type as the 
NAME parameter variable. Combinations allowed for the 
NAME and VALUE parameters are: 

NAME Type VALUE Type _ 

Integer Integer constant or variable reference. 

Character Character constant or variable reference. 

Boolean Boolean constant or variable reference. 


Ordinal 

Cell 

Pointer 

String 


Ordinal name or variable reference. 
Integer constant or variable reference. 
Integer constant or variable reference. 
String constant or variable reference. 


Array, record. Variable reference (byte-aligned 

set, or sequence and unpacked). 

This parameter is required. 
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MODULE or M 

Name of the module that contains the NAME parameter 
variable. 

Omission causes the module executing when Debug gained 
control or the module specified by the CHANGE _DEFAULT 
subcommand to be used. 

PROCEDURE otP 

Name of the procedure that contains the NAME parameter 
variable. If the PROCEDURE parameter is specified, the 
NAME parameter variable must exist in this procedure or 
exist in the containing procedure or module. If an inactive 
procedure is specified, the automatic variables cannot be 
changed. 

Omission causes the procedure executing when Debug gained 
control or the procedure specified by the CHANGE_ 
DEFAULT subcommand to be used. 

RECURSIONJLEVEL or RL 

The particular call of a recursive procedure to be used. Specify 
a positive integer greater than zero. If RECURSION _ 
DIRECTION=FORWARD, use a value of 1 for the first call, 2 
for the second call (the one called by the first call), and so on. 
If RECURSION_DIRECTION=BACKWARD, use 1 for the 
most recent call, 2 for the predecessor, and so on. 

Recursion only applies to program variables stored on the 
stack. Recursion cannot apply to variables stored in either a 
common block or the $STATIC section. 

Omission causes 1 to be used. 
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Order in which calls to a recursive procedure are searched. 
This parameter controls how the value of the RECURSION_ 
LEVEL parameter is interpreted. Specify one of the following 
keywords: 

FORWARD 

A RECURSION_LEVEL of 1 specifies that the first call to 
the procedure is used, a 2 specifies the second call, and so 
on. 


BACKWARD 

A RECURSION_LEVEL of 1 specifies that the most 
recent call to the procedure is used, a 2 specifies its 
predecessor, and so on. 

Recursion only applies to program variables stored on the 
stack. Recursion cannot apply to variables stored in either a 
common block or the $STATTC section. 

Omission causes BACKWARD to be used. 

STATUS 

Optional SCL status variable in which the completion status 
of the subcommand is returned. If omitted and an error does 
not occur. Debug processes the next subcommand. If omitted 
and an error occurs, the status value is returned to 
$RESPONSE and to the Debug output file if $RESPONSE is 
connected to that file. This file is normally connected during 
interactive debugging. 

Examples The following subcommand changes the value of 
VARIABLE 1: 

change_program_value name=variable1 value=3 

The following subcommand changes the value of INDEX: 

change_program_value name=index value=63 .. 
module=ff_pp procedure=gg_pg 
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CHANGE.REGISTER 

Purpose Changes the value of the P, A, or X registers that are 

associated with the procedure executing when Debug gained 
control. 

Format CHANGE .REGISTER or 

CHANGE.REGISTERS or 
CHAR 

KIND = keyword, value 

NUMBER = keyword value or list of integer 

VALUE = integer or string 

TYPE = keyword value 

STATUS = status variable 

Parameters KIND or K 

Kind of register or registers to change. Specify one of the 
following keywords: 

P The P register. 

A The A registers. 

X The X registers. 

Omission causes P to be used. 

NUMBER or N 

Number of the register or registers to change. Specify a set of 
one or more integers or ranges of integers from 0 to 15, or the 
keyword ALL. An informative message is issued for each 
referenced register whose value was not saved in the current 
stack frame and, therefore, cannot be changed. This 
parameter is ignored if KIND=P since there is only one P 
register. 

Omission causes 0 to be used. 
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VALUE or V 

New value of the register. If KIND is P or A, VALUE can be: 

• An integer in the range 0 through OFFFFFFFFFFFF 
hexadecimal. 

• A hexadecimal string containing a maximum of 12 
hexadecimal digits (spaces are ignored); each hexadecimal 
digit corresponds to 4 bits. 

The upper 4 bits are ignored when changing the P register 
since the ring number in P cannot be changed. 

If KIND is X, VALUE can be: 

• An integer ranging from -7FFFFFFFFFFFFFFF 
hexadecimal to 7FFFFFFFFFFFFFFF hexadecimal. 

• A hexadecimal string containing a m aximum of 16 
hexadecimal digits (spaces are ignored); each hexadecimal 
digit corresponds to 4 bits. 

• An ASCII string containing a maximum of eight ASCII 
characters; each character corresponds to one byte. 

Tlie upper bits of the register are set to 0 if an integer is 
positive or to 1 if an integer is negative and the value does not 
fill the register. A string value is left-justified with remaining 
bytes unchanged. 

This parameter is required. 

TYPE or T 

Type of data specified by the VALUE parameter. Specify one 
of the following keywords: 

ASCII (A) VALUE is an ASCII string. 

HEX (H) VALUE is a hexadecimal string. 

INTEGER (I) VALUE is an integer. 

Omission causes HEX to be used for string values and 
INTEGER to be used for numeric values. 
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STATUS 

Optional SCL status variable in which the completion status 
of the subcommand is returned. If omitted and an error does 
not occur, Debug processes the next subcommand. If omitted 
and an error occurs, the status value is returned to 
$RESPONSE and to the Debug output file if $RESPONSE is 
connected to that file. This file is normally connected during 
interactive debugging. 

If the CHANGE _ REGISTER subcommand contains an error 
before the STATUS parameter, the remainder of the 
subcommand is skipped. Therefore, the contents of the 
STATUS parameter does not reflect the status of the 
subcommand. 

Examples The following subcommand changes the current value of the 
P register to OA02200004500 hexadecimal. The upper 4 bits for 
the ring number are ignored. 

change_register kind=p, .. 
value=0a02200004500(16) 

The following subcommand changes the current value of the 
X7 register to ’abcdefgh’: 

change_register kind=x, number=7, .. 
value='abcdefgh* type=ascii 
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DELETE.BREAK 

Purpose Deletes one or more break definitions. 

Format DELETE _BREAK or 

DELETElBREAKS or 
DELB 

BREAK = keyword value or list of name 

STATUS = status variable 

Parameters BREAK or BREAKS or B 

Break definitions to be deleted. If the keyword ALL appears in 
the list of break names, all breaks are deleted. An informative 
message is issued if a specified break name does not exist; 
however, all subsequent breaks in the list are processed. 

This parameter is required. 

STATUS 

Optional SCL status variable in which the completion status 
of the subcommand is returned. If omitted and an error does 
not occur. Debug processes the next subcommand. If omitted 
and an error occurs, the status value is returned to 
$RESPONSE and to the Debug output file if $RESPONSE is 
connected to that file. This file is normally connected during 
interactive debugging. 

If the DELETE _ BREAK subcommand contains an error 
before the STATUS parameter, the remainder of the 
subcommand is skipped. Therefore, the contents of the 
STATUS parameter does not reflect the status of the 
subcommand. 

Examples The following subcommand deletes break definitions Bl, B2, 
and B3: 

delete_breaks breaks=(b1,b2,b3) 

The following subcommand deletes all break definitions: 
delete_breaks all 

The following subcommand deletes break definition B4- 
delete_break b4 
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DISPLAY_BREAK 

Purpose Displays break definitions. The break name, events, address, 
and any subcommands associated with the break are 
displayed. 

Format DISPLAY_BREAK or 

DISPLAY_BREAKS or 
DISB 

BREAK = keyword value or list of name 
OUTPUT = file 
STATUS = status variable 

Parameters BREAK or BREAKS or B 

Break definitions to be displayed. If the keyword ALL appears 
in the list of break names, all break definitions are displayed. 
An informative message is issued if a specified break name 
does not exist; however, all subsequent breaks in the list are 
processed. 

Omission causes all break definitions to be displayed. 
OUTPUT or O 

File on which the break definitions are written. You can 
specify a file position as part of the file name. Omission 
causes the current default Debug output file to be used. 

STATUS 

Optional SCL status variable in which the completion status 
of the subcommand is returned. If omitted and an error does 
not occur, Debug processes the next subcommand. If omitted 
and an error occurs, the status value is returned to 
$RESPONSE and to the Debug output file if $RESPONSE is 
connected to that file. This file is normally connected during 
interactive debugging. 

Examples The following subcommand displays all break definitions-' 
display_breaks 
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Debug then displays information similar to the following: 

— Break B1 

—event(s) = execution 

— Location: M=main_module L=26 

--Break B2 

—event(s) = execution 

— Location: M=moduLe_two L=13 B0=16 

— Break B3 

— event(s) = execution 

— location: M=module_two L=16 

— Break BA 

—event(s> = execution 

— Location: M=*uLtipLication_module L=7 

The following subcommand displays break definitions Bl, B2, 
and B4: 

display_breaks breaks=(b1,b2,bA) 

Debug displays the following: 

— Break Bl 

— event(s) = execution 

— Location: M=main_module L=26 

— Break B2 

—event(s) = execution 

— Location: M=module_two L=14 

—Break BA 

—event(s) = execution 

— location: M=multiplication_module L=7 
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DISPLAY.CALL 

Purpose Displays information about the dynamic call chain. Usually 
the procedure name, module name, and line number of each 
call are shown. Only the procedure or module name and byte 
offset from the beginning of the procedure or module are 
shown if you inhibit Debug tables when compiling your 
program. Only machine addresses are shown for internal 
NOS/VE calls. 

Format DISPLAY _CALL or 

DISPLAY CALLS or 
DISC 

COUNT = integer or keyword value 
START = integer 

DISPLAY_OPTION = list of keyword value 
OUTPUT=file 
STATUS = status variable 

Parameters COUNT or C 

Number of calls to be displayed. Specify a positive integer 
greater than zero or the keyword ALL If you specify a value 
greater than the number of existing calls, all calls are 
displayed. 

Omission causes all calls to be displayed. 

START or S 

Call on the chain to be displayed first. Thus, it is possible to 
skip the most recent calls. Specify a positive integer greater 
than zero. The value 1 represents the most recent call, 2 
represents the predecessor of the most recent call, and so 
forth. 

Omission causes 1 to be used. 

An informative message is issued if the number of calls you 
specify is greater than the actual number of calls. 

DISPLA Y_ OPTION or DISPLA Y_ OPTIONS or DO 

Type of information to be displayed. Specify one or more of 
the following keywords: 

USER_CALLS (UC) 

Causes only calls that are in user code to be displayed. 
SYSTEM_CALLS (SC) 

Causes only calls that are not part of the user code to be 
displayed. 
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ALL _ CALLS (AC) 

Causes both user calls and system calls to be displayed. 

VARIABLE _ VALUES (W) 

Causes all variables known to the procedure to be 
displayed. 

Omission causes only USER _ CALLS to be displayed. 

OUTPUT or O 

File on which the call information is written. You can specify 
a file position as part of the file name. 

Omission causes the current Debug output file to be used. 

STATUS 

Optional SCL status variable in which the completion status 
of the subcommand is returned. If omitted and an error does 
not occur, Debug processes the next subcommand. If omitted 
and an error occurs, the status value is returned to 
$RESPONSE and to the Debug output file if $RESPONSE is 
connected to that file. This file is normally connected during 
interactive debugging. 

Examples The following subcommand displays the first two user calls 
on the call chain: 

display_calls count=2 

Debug displays information similar to the following: 

— Traceback from procedure MULT module MULTIPLICATION 
MODULE at line 7 

— Called from procedure P module MODULE_TWO at line 13 
byte offset 36 

The following subcommand displays all of the user calls on 
the call chain beginning with the second most recent call: 

display_calls start=2 

Debug displays information similar to the following: 

-- Called from procedure P module M0DULE_TW0 at line 13 
byte offset 36 

— Called from procedure MAIN module MAIN_MODULE at 
line 25 byte offset 44 
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The following subcommand writes all of the user calls on the 
call chain to FILE1, the output file specified. Because the 
DISPLAY_OPTION parameter is omitted, only user calls are 
written to FILE1. 

display_calls count=all output=file1 status=stat 
The contents of FILE 1 is similar to the following: 

— Traceback from procedure MULT module MULTIPLICATION 

MODULE at line 7 

— Called from procedure P module M0DULE_TW0 at line 13 

byte offset 36 

— Called from procedure MAIN module MAIN_MODULE at line 

25 byte offset 44 

The following subcommand displays all calls (both user calls 
and system calls, if any) and all variables known to the 
procedure. 

display_call display_option=(all_calls,variable_values) 
Debug displays information similar to the following: 

— Traceback from procedure MAIN module MODULE_MAIN at 

line 21 byte offset 8 


— DISPLAY OF ALL VARIABLES IN MAIN 

B = ** INVALID BOOLEAN VALUE ** 

I = 576460752303423487 
J = 268435456 
K = 0 
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DISPLA Y_DEBUGGING_ ENVIRONMENT 


Purpose Displays the following information about the environment of 
your debugging session: current defaults for module, 
procedure, Debug input file, and Debug output file; the total 
number of breaks you have set; information about step mode; 
and the location in your program where execution stopped. 

Format DISPLAY_DEBUGGING_ENVIRONMENT or 

DISDE 

DISPLA Y_ OPTION = list of keyword value 
OUTPUT = file 
STATUS = status variable 

Parameters DISPLA Y_ OPTION or DISPLA Y_ OPTIONS or DO 

Type of information to be displayed. Specify one or more of 
the following keywords: 

ALL 

Defaults, breaks, step mode attributes, and the user 
address are displayed. 

BREAKS (B) 

The number of breaks you have set, the number of breaks 
currently in use by Debug, and the number of unused 
breaks are displayed. 

DEFAULTS (D) 

The current default values for module, procedure, Debug 
input file, and Debug output file are displayed. 

Unless the CHANGE_DEFAULT subcommand has been 
specified, the default module and procedure is where 
execution has stopped in your task. The text $CURRENT 
is output if module or procedure has not been initialized. 

STEP_MODE (SM) 

The current step mode attributes are displayed. 
USER_ADDRESS (UA) 

The location where execution has stopped in your program 
is displayed. 

Omission causes ALL to be used. 
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OUTPUT or 0 

File on which the call information is written. You can specify 
a file position as part of the file name. Omission causes the 
current Debug output file to be used. 

STATUS 

Optional SCL status variable in which the completion status 
of the subcommand is returned. If omitted and an error does 
not occur, Debug processes the next subcommand. If omitted 
and an error occurs, the status value is returned to 
$RESPONSE and to the Debug output file if $RESPONSE is 
connected to that file. This file is normally connected during 
interactive debugging. 

Examples The following subcommand writes defaults, breaks, step mode 
attributes, and location where execution stopped to the 
current default Debug output file: 

display_debugging_environment 

Debug displays information similar to the following: 


— Default module is SCURRENT. 

— Default procedure is SCURRENT. 

— Default debug_input file is :$L0CAL.COMMAND. 

— Default debug_output file is :$LOCAL.$OUTPUT. 

— The number of breaks set by the user is 4. 

— The number of breaks in use by DEBUG is 0. 

— The number of available breaks is 60. 

— Step_mode is OFF. 

— Execution is currently stopped at B 04D 00000132 which, 
in higher symbolic terms is M=m L=16 
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The following subcommand displays the number of breaks 
set, the number of unused breaks, and the location where 
execution stopped: 

display_debugging_environment .. 
display_options=(b,ua) 

Debug displays information similar to the following: 

— The number of breaks set by the user is 4. 

— The number of breaks in use by DEBUG is 0. 

— The number of available breaks is 60. 

— Execution is currently stopped at B 04D 00000132 which, 
in higher symbolic terms is M=m L=16 

The following subcommand writes defaults, breaks, step mode 
attributes, and location where execution stopped to file FILE1 
and returns the subcommand status to variable SS: 

display_debugging_environment .. 
display_options=all output=file1 status=ss 

The contents of FIT.El is similar to the following: 

— Default module is SCURRENT. 

— Default procedure is SCURRENT. 

— Default debug_input file is :$L0CAL.COMMAND. 

— Default debug_output file is :$L0CAL.$0UTPUT. 

— The number of breaks set by the user is 4. 

— The number of breaks in use by DEBUG is 0. 

— The number of available breaks is 60. 

— Step_mode is OFF. 

— Execution is currently stopped at B 04D 00000132 which, 
in higher symbolic terms is M=m L=16 
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I 


DISPLAY_MEMORY 


| 


Purpose Displays information located at any address to which ytm 

have read access. This subcommand allows you to debug your 
program even when compiler-generated symbol tables are not 
available, and to display memory areas that do not 
correspond to program identifiers. Each display line shows 
the memory contents in hexadecimal and ASCII formats; the 
relative byte offset from the initial address is also shown. 

The compiler-generated attributes list shows the section name 
and offset for all variables. You can reference static variables 
by specifying section name and byte offset. You can reference 
variables on the stack by specifying the machine address of 
the stack frame and byte offset. You can obtain the address of 
the stack frame of the procedure executing when Debug got 
control by displaying register Al. You can obtain the address 
of other stack frames by displaying the save area of the 
wanted stack frame using the DISPLAY_STACK_FRAME 
subcommand and obtaining the value of register Al from that 
stack frame. You can also use the DISPLAY_PROGRAM_ 
VALUE subcommand to display program variables when 
symbol tables are available. 

Format DISPLAY MEMORY or 

DISM 
address 

B YTE_ OFFSET = integer 
BYTE_COUNT = integer 
REPEAT_COUNT = integer or keyword value 
OUTPUT = file 
STATUS = status variable 

Parameters address 

Memory location to be displayed. The memory location is 
specified by one or more of the following address parameters: 

SECTION = name or keyword value 
MODULE = name 
ADDRESS = integer 
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SECTION (SEC) 

Memory section containing the data to be displayed. Specify 
one of the following: 

• Working storage section name of a CYBIL program. 

• A common block name (for languages that support 
common blocks). 

• $BINDING, which is the memory section containing the 
links to external procedures and the data of the module. 

• $LITERAL, which is the memory section containing the 
literal data (that is, long constants) of the module. 

• $STATIC, which is the memory section containing the 
static (not on the run-time stack) variables not explicitly 
allocated to a named section of the module. 

• CYB$DEFAULT_HEAP, which is the memory section 
containing the default heap of CYBIL. 

When you use SECTION to specify an address, you must 
qualify it with the MODULE parameter. You can use the 
BYTE_OFFSET parameter to modify the starting address of 
memory to be displayed. 

Omission indicates that the memory address is specified by 
the ADDRESS parameter. 

MODULE (M) 

Module containing the data to be displayed. The MODULE 
parameter cannot be specified unless the SECTION 
parameter is specified. 

Omission indicates that the memory address is specified by 
the ADDRESS parameter. 
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ADDRESS (A) 

Address of the first byte of memory to be displayed. Its value 
is expressed in the form 

rsssoooooooo(16) 

where r is the ring number, sss is the segment number, and 
oooooooo is the offset from the beginning of the segment. You 
can use the BYTE _ OFFSET parameter to modify the starting 
address of memory to be displayed. 

Omission indicates that the address is specified by the 
SECTION and MODULE parameters. 

B YTE_ OFFSET or BO 

Offset to the base address established by one of the address 
parameters. Specify a positive integer. Its value is added to 
the base address to form a new address. 

The address generated by adding BYTE _ OFFSET to the base 
address must be within the memory block implied by the base 
address. The block size is the length of the section when the 
SECTION parameter is specified, and the length of the 
segment containing the machine address when the 
ADDRESS parameter is specified. 

Omission causes 0 to be used. 

BYTE _COUNT or BC 

Number of bytes in the item to be displayed. Specify a positive 
integer greater than zero. 

Omission causes 1 to be used. 

REPEAT_COUNT or RC 

Number of memory areas (items) of length BYTE_COUNT to 
be displayed. Specify a positive integer. The maximum 
amount of memory that can be displayed is limited to the 
block size implied by address (section length for SECTION 
and segment length for ADDRESS). The keyword ALL or a 
large integer causes all memory from the specified address to 
the end of the memory block to be displayed. 

Omission causes 1 to be used. 
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OUTPUT or O 

File on which the displayed information is written. You can 
specify a file position as part of the file name. 

Omission causes the current Debug output file to be used. 
STATUS 

Optional SCL status variable in which the completion status 
of the subcommand is returned. If omitted and an error does 
not occur, Debug processes the next subcommand. If omitted 
and an error occurs, the status value is returned to 
$RESPONSE and to the Debug output file if $RESPONSE is 
connected to that file. This file is normally connected during 
interactive debugging. 

Examples The following subcommand displays the first three bytes of 
the literal memory section for module MODI: 

displayjnemory section=$literal module=mod1 .. 
byte_count=3 

The following subcommand displays the first 32 bytes of the 
memory section DATA1 for module MOD2 as separate items: 

display jnemory section=data1 module=mod2 .. 
repeat_count=4 

The following subcommand displays the first 200 bytes of 
memory starting from the specified address: 

display jnemory address=0602400000224(16) .. 
byte_count=8 repeat_count=25 
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Purpose Displays the value of the specified program variable (except a 
boolean value) as it appears in the source program or in 
hexadecimal format. 

Format DISPLAY_PROGRAM_VALUE or 

DISPV 

NAME = program name or keyword value 
MODULE = name 
PROCEDURE = name 
RECURSION_LEVEL = integer 
RECURSION_DIRECTION= keyword value 
TYPE = keyword value 
OUTPUT = file 
STATUS = status variable 

Parameters NAME or N 

Name of the program element whose value is to be displayed 
or the keyword $ALL. Specifying $ALL causes all variables in 
the specified (or default) procedure to be displayed. 

A program element can be one of the following: 

• Simple variable or constant name 

• Subscripted name 

• Field reference 

• Pointer reference 

Subscripts can be constants or variables but not expressions. 
NAME cannot be a substring. 

The variable must be used in your program. 

Because names can be long, SCL string variables can be used 
as aliases for them. To do so, assign the SCL variable to a 
string containing the identifier. Then use the SCL variable 
preceded by a question mark as the value of the NAME 
parameter. 

This parameter is required. 
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MODULE or M 

Name of the module containing the NAME parameter 
variable. 

Omission causes the module executing when Debug gained 
control or the module specified by the CHANGE_DEFAULT 
subcommand to be used. 

PROCEDURE or P 

Name of the procedure containing the program name. If you 
specify a procedure that is not in the active call chain, its 
automatic variables cannot be displayed because it has no 
stack frame. 

Omission causes the procedure executing when Debug gained 
control to be used if MODULE is also omitted. Otherwise, 
there is no default procedure when MODULE is specified and 
PROCEDURE is not; the program name must exist at the 
module level. 

RECURSION JLEVEL or RL 

The particular call of a recursive procedure to be used. Specify 
a positive integer greater than zero. If RECURSION_ 
DIRECTION=FORWARD, use a value of 1 for the first call, 2 
for the second call (the one called by the first call), and so on. 
If RECURSION_DIRECTION=BACKWARD, use 1 for the 
most recent call, 2 for the predecessor, and so on. 

Omission causes 1 to be used. 

RECURSION_DIRECTION or RD 

Order in which calls to a recursive procedure are searched. 
This parameter controls how the value of the RECURSION_ 
LEVEL parameter is interpreted. Specify one of the following 
keywords: 

FORWARD (F) 

A RECURSION _ LEVEL of 1 specifies that the first call to 
the procedure is used, a 2 specifies the second call, and so 
on. 


BACKWARD (B) 

A RECURSION _ LEVEL of 1 specifies that the most 
recent call to the procedure is used, a 2 specifies its 
predecessor, and so on. 

Omission causes BACKWARD to be used. 
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TYPE or T 

Format of the value to be displayed. If the keyword HEX is 
specified, Debug displays the variable name, the process 
virtual address (PVA) that corresponds to the start of the 
variable, the memory representation of the variable’s value, 
and the ASCII representation of memory (with a question 
mark representing an unprintable character). If the requested 
data is not contained in a contiguous block of memory, an 
error message is issued. 

Omission causes Debug to print the variable name and the 
value of the variable as it is defined in the source program 
rather than in hexadecimal format. 

OUTPUT or O 

File where the display information is written. You can specify 
a file position as part of the file name. 

Omission causes the current Debug output file to be used. 

STATUS 

Optional SCL status variable in which the completion status of 
the subcommand is returned. If omitted and an error does not 
occur, Debug processes the next subcommand. If omitted and an 
error occurs, the status value is returned to $RESPONSE and to 
the Debug output file if $RESPONSE is connected to that file. 
This file is normally connected during interactive debugging. 

Examples The following subcommand displays the value of I from the 

current module: 

display_program_value name=i 
Debug displays the following: 
i = 576460752303423487 

The following subcommand displays the value of J from 
procedure MAIN in the current module: 

dispLay_program_value name=j .. 
procedure=main 

Debug displays the following: 

i = 268435456 

The following subcommand displays the value of all variables 
from the current module: 

display_program_value Sail 

Debug displays the following: 

— DISPLAY OF ALL VARIABLES IN MAIN 

B = ** INVALID BOOLEAN VALUE ** 

I = 576460752303423487 
J = 268435456 
K = 0 
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DISPLAY.REGISTER 

Purpose Displays the contents of the P, A, or X registers that are 

associated with the procedure executing when Debug gained 
control. 

Format DISPLAY _ REGISTER or 

DISPLAY REGISTERS or 
DISR 

KIND = list of keyword value 

NUMBER = keyword value or list of integer 

TYPE = keyword value 

OUTPUT = file 

STATUS = status variable 

Parameters KIND or K 

Kind of register or registers to display. Specify one of the 
following keywords: 

P The P register. 

A The A registers. 

X The X registers. 

Omission causes P to be used. 

NUMBER or N 

Number of the register or registers to display. Specify a set of 
one or more integers or ranges of integers from 0 to 15, or the 
keyword ALL. An informative message is issued for each 
referenced register whose value was not saved in the current 
stack frame and, therefore, cannot be displayed. This 
parameter is ignored if KIND=P since there is only one P 
register. 

Omission causes 0 to be used. 
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TYPE or T 

Type of the displayed register values. Specify one of the 
following keywords: 

ASCII (A) 

Displays ASCII string values. 

HEX (H) 

Displays hexadecimal string values. 

INTEGER® 

Displays integer values. 

Omission causes HEX to be used for string values and 
INTEGER for numeric values. 

OUTPUT or O 

File on which the register contents are written. You can 
specify a file position as part of the file name. 

Omission causes the current Debug output file to be used. 
STATUS 

Optional SCL status variable in which the completion status 
of the subcommand is returned. If omitted and an error does 
not occur, Debug processes the next subcommand. If omitted 
and an error occurs, the status value is returned to 
$RESPONSE and to the Debug output file if $RESPONSE is 
connected to that file. This file is normally connected during 
interactive debugging. 
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Examples The following subcommand displays the contents of the P 
register in hexadecimal: 

display_register p 

Debugs displays the following: 

P=B 04D 00000040 

The following subcommand displays the contents of the A8 
register in hexadecimal: 

displ.ay_register kind=a number=8 type=hex 

Debug displays the following: 

A8=8 04E 00000442 

The following subcommand displays the contents of the X4, 
X5, X6, X7, X8, X9, and XA registers in hexadecimal: 

display_register kind=x number=4..10 

Debug displays the following: 

X4=00000000 10000000 
X5=OOOOOOOG 00000008 
X6=00000000 OOOOOOOD 
X7=00000000 0000001D 
X8=00000000 00000000 
X9=00000000 00000008 
XA=00000000 00000300 
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DISPLAY_STACK_FRAME 

Purpose Displays the contents of one or more stack frames. Values are 

displayed in hexadecimal. 

Format DISPLAY_STACK_FRAME or 

DISPLAY_STACK_FRAMES or 
DISSF 

COUNT = integer or keyword value 
START = integer 

DISPLAY_OPTION = list of keyword value 
OUTPUT = file 
STATUS = status variable 

Parameters COUNT or C 

Number of stack frames to be displayed. Specify a positive 
integer. An integer value greater than the number of existing 
stack frames or the keyword ALL causes all stack frames to 
be displayed. 

Omission causes one stack frame to be displayed. 

START or S 

Stack frame to be displayed first. Specify a positive integer 
greater than zero. The value 1 represents the most recent 
stack frame, 2 represents its predecessor, and so on. 

Omission causes 1 to be used. 

DISPLA Y_ OPTION or DISPLA V. OPTIONS or DO 
Area of the stack frames to be displayed. Specify one or more 
of the following keywords: 

AUTO (A) 

Area containing the automatic (dynamically allocated) 
variables of the procedure. 

SAVE (S) 

Area containing a copy of the registers of the procedure as 
they existed at the time of a call or trap. 

ALL 

Both the automatic and save areas. 

Omission causes ALL to be used. 

OUTPUT or O 

File on which the stack frame values are written. You can 
specify a file position as part of the file name. 

Omission causes the current Debug output file to be used. 
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Examples 


STATUS 

Optional SCL status variable in which the completion status 
of the subcommand is returned. If omitted and an error does 
not occur, Debug processes the next subcommand. If omitted 
and an error occurs, the status value is returned to 
$RESPONSE and to the Debug output file if $RESPONSE is 
connected to that file. This file is normally connected during 
interactive debugging. 


The following subcommand displays the automatic and save 
areas of the most recent stack frame: 


display_stack_frame count=1 
Debug displays the following: 


STACK FRAME 001 
00000000 00000000 
00000008 00000000 
00000010 304COOOO 
00000018 00000000 
00000020 FFFFFFFF 
00000028 OOOOBOID 
00000030 OOOOB04E 
00000038 00000000 

00000040 FFFFFFFF 
00000048 B04EOOOO 
00000050 B04E0000 

SAVE AREA 

P=8 040 000000AC 
UM=FFF7 UCR=0080 

A0=B 04E 000004DO 
A2=B 04E 00000430 
A4=B 04E 00000400 
A6=B 04E 000004AF 
A8=8 04E 00000442 
AA=8 04E OOOOOA88 
AC=F FFF 80000000 
AE=F FFF 80000000 


SEGMENT=04E 
00000000 
00000000 
00C0FFFF OL 

00000000 
FFFFFFOC 

000D4A2E J. 

00000400 N 

00000000 
FFFFFEOC 

04A05D58 N IX 

04AF0430 N 0 


VMID=0 

MCR=0000 

A1=B 04E 00000478 
A3=B 04C 00000000 
A5=B 04B 00000020 
A7=B 04E 000004AF 
A9=B 04E 000006AO 
AB=F FFF 80000000 
AD=B 04E 000010D8 
AF=B 006 OOOOBB98 


XO=OOOOB04D 00040254 
X2=OOOOFFFF 80000000 
X4=00000000 00000064 
X6=00000000 00000000 
X8=00000000 00000000 
XA=00000000 00000300 
XC=0000FFFF 80000000 
XE=0000FFFF 80000000 


X1=OOOOFFFF 80000000 
X3=00000000 00000000 
X5=FFFFFFFF FFFFFEOC 
X7=00000000 0000001D 
X9=00000000 00000008 
XB=0000FFFF 80000000 
XD=0000FFFF 80000000 
XF=00000000 00000008 
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The following subcommand displays the save area of the 
most recent stack frame: 

display_st ac k_frame display_opt i on=sa ve 

Debug displays the following: 


STACK FRAME 001 SEGMENT=04E 

SAVE AREA 

P=B 04D 000000AC VMID=0 

UM=FFF7 UCR=0080 MCR=0000 


A0=8 04E 000004DO 
A2=B 04E 00000430 
A4=B 04E 00000400 
A6=B 04E 000004AF 
A8=B 04E 00000442 
AA=B 04E OOOOOA88 
AC=F FFF 80000000 
AE=F FFF 80000000 


A1=B 04E 00000478 
A3=B 04C 00000000 
A5=B 04B 00000020 
A7=B 04E 000004AF 
A9=B 04E 000006AO 
AB=F FFF 80000000 
AD=8 04E 000010D8 
AF=B 006 0000BB98 


X0=0000B04D 00040254 
X2=0000FFFF 80000000 
X4=00000000 00000064 
X6=00000000 00000000 
X8=00000000 00000000 
XA=00000000 00000300 
SC=0000FFFF 80000000 
XE=0000FFFF 80000000 


X1=OOOOFFFF 80000000 
X3=00000000 00000000 
X5=FFFFFFFF FFFFFEOC 
X7=00000000 0000001D 
X9=00000000 00000008 
XB=OOOOFFFF 80000000 
XD=0000FFFF 80000000 
XF=00000000 00000008 


The following subcommand displays the automatic and save 
areas of three stack frames beginning with the second most 
recent one: 

display_stack_frames count=3 start=2 
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Debug displays the following: 

STACK FRAME 002 SEGMENT=04E 

00000000 0000BQ4E 000006A0 N 

00000008 7FE4B04E 00000A88 N 

00000010 04A1FFFF 80000000 

00000018 00000000 00000017 

00000020 00000000 0000001D 

00000028 B04EOOOO 04AOOOOO N 

SAVE AREA 

P=B 04D 0000011C VMID=0 

UM=FFF7 UCR=0000 MCR=0000 

AO=B 04E 00000550 A1=B 04E 00000520 

A2=B 04E 000004DO A3=B 04C 00000040 

A4=B 04E 00000480 A5=8 04B 00000020 


X2=0000FFFF 80000000 

STACK FRAME 003 SEGMENT=04E 


00000000 

00000000 

00000000 



00000008 

00000000 

00000000 



00000048 

B04EOOOO 

04A05D58 

N 

3X 

00000050 

B04E0000 

04AF0430 

N 

0 

SAVE AREA 





P=B 04D 000000AC 

VMID=0 



UN=FFF7 

UCR=0000 

MCR=0000 




A0=8 04E 000004DO 
A2=B 04E 00000430 
A4=B 04E 00000400 


A1=B 04E 00000478 
A3=B 04C 00000000 
A5=B 04B 00000020 


X2=0000FFFF 80000000 X3=00000000 00000017 


X4=00000000 

00000064 



STACK FRAME 004 

SEGMENT=04E 


00000000 

B04EOOOO 

01584810 

N XH 

00000008 

0000604E 

00000128 

N ( 

000002F8 

B04EOOOO 

001E0000 

N 

00000300 

01020000 

00000000 


SAVE AREA 




P=B 01D OOOD4996 

VMID=0 


UM=FFF7 1 

JCR=0400 

MCR=0000 



AO=B 04E 00000430 A1=B 04E 00000128 
A2=F FFF 80000000 A3=B 01B 00005D58 
A4=8 04E 00000000 A5=B 04E 00000400 
A6=B 04E 000001 DO 

X0=00000000 00020060 
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QUIT 


QUIT 

Purpose 


Format 


Parameter 


Terminates the Debug session and returns control to the 
NOS/VE operating system. The session is terminated 
immediately; the program is not executed to completion. 

QUIT or 
QUI 

STATUS = status variable 
STATUS 

Optional SCL status variable in which the completion status 
of the subcommand is returned. If omitted and an error does 
not occur, Debug processes the next subcommand. If omitted 
and an error occurs, the status value is returned to 
$RESPONSE and to the Debug output file if $RESPONSE is 
connected to that file. This file is normally connected during 
interactive debugging. 
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RUN 


RUN 

Purpose Initiates or resumes program execution once Debug has 

gained control. Execution continues until Debug again gains 
control. If the program has run to completion, entering the 
RUN subcommand terminates the program and returns 
control to the NOS/VE operating system. 

Execution begins at the instruction whose address is 
contained in the P register or at the condition handler (if there 
is one) of the program for the event that caused Debug to gain 
control. (Refer to the SCL Language Definition manual for a 
discussion of condition handlers.) If the P register points to 
the instruction that caused the event (such as division by 
zero), the same event will occur immediately after entering the 
RUN subcommand. In this case, you must change the value 
in the P register (use the CHANGE_REGISTER 
subcommand) or change the value of one of the operands (use 
the CHANGE _PROGRAM_ VALUE subcommand) before 
entering the RUN subcommand. 

When Debug processes the RUN subcommand, all previously 
created SCL blocks (except SET_BREAK subcommand 
information and the name of the current Debug input file) are 
lost. This means that some information about SCL 
commands, such as IF/THEN blocks or WHILE/FOR loops 
that span RUN subcommands, is lost. In the following 
example, SCOPE = JOB will retain the variables. 

DB/create_variable name=count .. 

DB../kind=integer scope=job value=0 
DB/set_break break=one line=1 command='run' 
DB/create_variable name=count .. 

DB../kind=integer scope=xref 

Format RUN 

STATUS = status variable 

Parameter STATUS 

Optional SCL status variable in which the completion status 
of the subcommand is returned. If omitted and an error does 
not occur, Debug processes the next subcommand. If omitted 
and an error occurs, the status value is returned to 
$RESPONSE and to the Debug output file if $RESPONSE is 
connected to that file. This file is normally connected during 
interactive debugging. 
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SET.BREAK 


SET_ BREAK 

Purpose Defines the break. You can specify one or more events and the 
location at which Debug is to take control. When the specified 
event occurs, program execution is suspended and a message 
informs you which break occurred. At this point, you can 
enter another Debug subcommand, or any command that can 
be processed by the operating system or an active command 
utility. 

Format SET BREAK or 
SET"BREAKS or 
SETB 

BREAK = name 

EVENT = list of keyword value 

address 

BYTE _OFFSET= integer 
BYTE_COUNT= integer 
COMMAND = string 
STATUS = status variable 

Parameters BREAK or B 

Name of the break definition. This name is used to reference 
the break definition in the DISPLAY_ BREAK and 
DELETE_BREAK subcommands. This name is displayed in 
the break report message when the break occurs. You cannot 
specify a break name of ALL (because ALL is used as a 
keyword in other Debug subcommands) or a break name that 
contains the dollar sign character ($). 

Omission causes Debug to assign a unique name. In this case, 
Debug notifies you of the name assigned. 

EVENT or EVENTS or E 

Events that must occur for the break to occur. If you specify 
more than one event, the break is honored if only one of the 
events occurs. Possible events can be any of the following 
keywords: 

ARITHMETIC .OVERFLOW (AO) 

Break when an arithmetic overflow occurs on an 
instruction in the specified address range. The P register 
points to the instruction that caused the overflow. 
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ARITHMETIC_SIGNIFICANCE (AS) 

Break when arithmetic significance is lost on an 
instruction in the specified address range. The P register 
points to the instruction that caused the loss of 
significance. 

BRANCH (B) 

Break before a branch to or a return from any location in 
the specified address range occurs. 

CALL(C) 

Break before a subprogram call occurs to any address in 
the specified address range. 

MVTOE.FAULT (DF) 

Break when division by zero occurs in an instruction in the 
specified address range. The P register points to the 
instruction that caused the division by zero. 

EXECUTION (E) 

Break before the instruction in the specified address range 
is executed. 

If the address is specified by the line number, not every fine 
is usable. For example, breaks cannot be set at IFEND 
statements because it is not obvious when control reaches 

them. 

EXPONENT _ O VE RFLOW (EO) 

Break when an exponent overflow occurs in an instruction 
in the specified address range. The P register points to the 
instruction following the one that caused the overflow. 

EXPONENT_UNDERFLOW (EU) 

Break when an exponent underflow occurs in an 
instruction in the specified address range. The P register 
points to the instruction following the one that caused the 
underflow. 

FLOATING_POINT_INDEFINITE (FPI) 

Break when the result of a floating-point operation is 
indefinite in an instruction in the specified address range. 
The P register points to the instruction following the one 
that caused the results to be indefinite. 
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SET_BREAK 


FLOATING_POINT_SIGNIFICANCE (FPS) 

Break when significance is lost during a floating-point 
operation in an instruction in the specified address range. 
The P register points to the instruction following the one 
that caused the loss of significance. This event will not 
occur unless your program sets the floating-point loss-of- 
significance bit in the user mask register. 

INVALID_BDP_DATA (IBD) 

Break when a business data processing (BDP) instruction 
fault occurs in an instruction in the specified address 
range. The P register points to the instruction that caused 
the fault. The BDP instructions are described in volume II 
of the virtual state hardware reference manual. 

READ (R) 

Break before a read occurs from the specified address 
range. The break occurs only if the first byte of the item to 
be read is within the address range. 

READ_NEXT_INSTRUCT10N (RNI) 

Break before the instruction in the specified address range 
is executed. 

WRITE (W) 

Break before a write occurs into the specified address 
range. The break occurs only if the first byte of the item to 
be written is within the address range. 

Omission causes EXECUTION to be used. 
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Debug gains control when the following events occur even if 
you do not set a break for them: 

ARITHMETIC.OVERFLOW 
ARITHMETIC .SIGNIFICANCE 
DIVIDE .FAULT 
EXPONENT.OVERFLOW 
EXPONENT.UNDERFLOW 
FLOATING _ POINT. INDEFINITE 
FLOATING.POINT. SIGNIFICANCE 
INVALID.BDP.DATA 

Specific breaks can be set for these events, however, so that a 
predefined set of commands or subcommands can be executed 
when Debug gains control. 

address 

Location at which the break occurs. For the break to occur, the 
specified event must occur within the range defined by the 
address parameters. All address parameters are interpreted as 
a single address. You can use the BYTE .COUNT and 
BYTE.OFFSET parameters to specify an address range. 
Omission indicates an address range of one byte. The address 
parameters are: 

LINE = integer 

SECTION = name or keyword value 
MODULE = name 
PROCEDURE = name 
ENTRY.POINT = name 
ADDRESS = integer 
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ONE (L) 

Line at which Debug gains control. Unless the MODULE 
parameter is also specified, the line number must exist in the 
module that was executing when Debug gained control or the 
default module set with the CHANGE _ DEFAULT 
subcommand. 

You can use BYTE _OFFSET and BYTE_COUNT to modify 
this parameter. 

Not all lines of a program can be referenced. Only executable 
statements that begin on a separate line can be referenced. A 
second or third statement on a line or a line containing the 
continuation of a statement cannot be referenced. In addition, 
IFEND lines cannot be referenced. 

Omission indicates that the break address is specified by 
another parameter. 

SECTION (SEC) 

A memory section. Specify one of the following: 

• Name of the working storage section as declared in the 
source program. 

• Name of a common block. 

• $BINDING, which is the memory section containing the 
links to external procedures and the data of the module. 

• CYB$DEFAULT_HEAP, which is the memory section 
containing the default heap for CYBIL. 

• $LITERAL, which is the memory section containing the 
literal data (that is, long constants) of the module. 

• $STATIC, which is the memory section containing the 
static (not on the run-time stack) variables that are not 
allocated to an explicitly named section of the module. 
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SET_BREAK 


Unless the MODULE parameter is also specified, the section 
must exist for the module that was executing when Debug 
gained control or the default module set with the CHANGE _ 
DEFAULT subcommand. The SECTION parameter cannot 
be specified for modules that are components of a bound 
module unless the section is a common block (refer to the 
discussion under Addressing Bound Modules earlier in this 
chapter). You can use the BYTE_OFFSET and BYTE_ 
COUNT parameters to modify this parameter. 

Omission indicates that the break address is specified by 
another parameter. 

MODULE (M) 

An address or qualification of another address specifier. If 
used alone, the MODULE parameter specifies an address (the 
first byte of the first code section of the module). Module 
represents only the first code section. MODULE cannot 
reference the code section of a component module of a bound 
module (refer to the discussion under Addressing Bound 
Modules earlier in this chapter). If used with the LINE, 
SECTION, or PROCEDURE address parameters, the 
MODULE parameter identifies the module containing the 
line, section, or procedure. If used to specify an address, the 
BYTE _OFFSET and BYTE _COUNT parameters can be used 
to modify the MODULE parameter. 

Omission causes the module executing when Debug gained 
control or the default module set with the CHANGE _ 
DEFAULT subcommand to be used. 


Revision B 


The Debug Utility 9-65 



SET_BREAK 


PROCEDURE (P) 

An address (the first byte of the code section of the procedure). 
Unless the MODULE parameter is also specified, the 
procedure must exist in the module that was executing when 
Debug gained control or the default module set with the 
CHANGE_DEFAULT subcommand. You can use the BYTE_ 
OFFSET and BYTE _ COUNT parameters to modify the 
PROCEDURE parameter. You cannot specify the LINE or 
SECTION address parameters with the PROCEDURE 
parameter. 

When a name is specified, this parameter indicates the 
procedure to be used. The name must be a procedure, function, 
or program. 

Omission indicates that the break address is specified by 
another parameter. 

ENTRY_POINT (EP) 

An entry point expressed as a name known to the loader. 
Specify a procedure or data name with an XDCL attribute 
subject to certain restrictions. (Refer to Attributes in chapter 3 
for a description of the XDCL attribute. Also, refer to the SCL 
Object Code Management manual for further information on 
restrictions.) You can use the BYTE_OFFSET and BYTE_ 
COUNT parameters to modify the ENTRY_POINT 
parameter. You cannot use other address parameters with this 
parameter. 

Omission indicates that the break address is specified by 
another parameter. 
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SET.BREAK 


ADDRESS (A) 

Address of the break event in the form 
rsssoooooooo( 16) 

where r is the ring number, sss is the segment number, and 
oooooooo is the offset within the segment. You can obtain 
machine addresses from the cross-reference and load maps for 
your program. You can use the BYTE_OFFSET and BYTE_ 
COUNT parameters to modify the ADDRESS parameter. You 
cannot use other address parameters with this parameter. 

Omission indicates that the break address is specified by 
another parameter. 

The address parameter is required. 

BYTE_ OFFSET or BO 

Offset to the base address established by one of the address 
parameters. Specify a positive integer. Its value is added to 
the base address to form a new address. The break is then set 
for this new address. 

Omission causes a value of zero to be used. 

BYTE _COUNT or BC 

Number of bytes in an address range. Specify a positive 
integer greater than zero. 

Omission causes 1 to be used. 
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COMMAND or COMMANDS or C 

String of commands or subcommands to be executed when the 
break is honored. These commands or subcommands can be 
processed by Debug, the operating system, or other active 
command processor. If a command in the string includes a 
quoted string, that string must be enclosed in two single 
quotes. After the commands in the string have been executed, 
commands are read from the current Debug input file unless 
the string contains a RUN subcommand. 

No break report message is issued before the commands in the 
string are executed. If you want a message to be displayed, 
include an SCL PUT_LINE command in the string. 

If an error is detected in one of the commands in the string, 
the break report message is issued, the error is reported, and 
commands are read from the Debug input file. The remaining 
commands in the string are not executed. 

Omission indicates that no commands are associated with the 
break. Commands are read from the Debug input file. 

STATUS 

Optional SCL status variable in which the completion status 
of the subcommand is returned. If omitted and an error does 
not occur, Debug processes the next subcommand. If omitted 
and an error occurs, the status value is returned to 
$RESPONSE and to the Debug output file if $RESPONSE is 
connected to that file. This file is normally connected during 
interactive debugging. 

If the SET_BREAK subcommand contains an error before the 
STATUS parameter, the remainder of the subcommand is 
skipped. Therefore, the contents of the STATUS parameter 
does not reflect the status of the subcommand. 
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Examples The following subcommand causes a break when execution 
reaches line 10 of module PROGl: 

set_break break=b1 line=10 module=prog1 

The following subcommand causes a break when a branch or 
return occurs to line 40 of the module executing when Debug 
gained control: 

set break break=b2 event=branch line=40 
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SET_STEP_MODE 

SET_STEP_MODE 

Purpose Enables you to execute a specified subset of a task and receive 
control. 

If you activate step mode, a RUN subcommand causes your 
program to execute for the specified unit. You are then 
prompted for further subcommand input. A string of 
subcommands can be associated with the step and will be 
processed each time the step is completed. Stepping with a 
unit of line or procedure is only available if the source 
program was compiled with the Debug optimization option 
(OPTIMIZATION_LEVEL=DEBUG). 

Activating step mode is an effective debugging aid but is 
expensive in terms of execution time. 

Format SET_STEP_MODE or 

SETSM 

MODE = keyword value 

UNIT = keyword, value 

MODULE = keyword value or list of name 

PROCEDURE - keyword value or list of name 

SPAN = integer 

COMMAND = string 

STATUS = status variable 

Parameters MODE 

Activates or deactivates step mode. Specify one of the 
following keywords-' 

ON 

Activates step mode. When step mode is on, a RUN 
subcommand causes one step to be executed. A step is 
defined by the UNIT parameter. 

OFF 

Deactivates step mode. When step mode is off, any 
remaining parameters are ignored. 

If you specify ON and step mode is already on, all previous 
values are replaced with the new values. 

This parameter is required. 
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UNIT or U 

Length of the step. Specify one of the following keywords: 
PROCEDURE (P) 

The step is reported each time a new procedure begins and 
after any prologue code for the procedure has executed. 

LINE (L) 

The step is reported before the code is executed for each line 
except for the procedure lines. 

Omission causes LINE to be used. 

MODULE or M 

The modules reported. This parameter is used with the UNIT 
parameter. Specify one of the following keywords or a list of 
modules: 

$ALL 

Reports a step that is in any module. 

$CURRENT 

Reports a step only if the step occurs in the module where 
the program is executing when step mode is activated. 

Using a list of modules causes a step to be reported only if the 
step occurs in a specified module. 

You cannot specify both the MODULE and the PROCEDURE 
parameters in the same SET_STEP_MODE subcommand. 

Omission causes the current value for the default module to be 
used. 
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1 


PROCEDURE or P 

The procedures reported. This parameter is used with the 
UNIT parameter. Specify one of the following keywords or a 
list of procedures: 

$ALL 

Reports a step that is in any procedure. 

$CURRENT 

Reports a step only if the step occurs in the procedure 
where the program is executing when step mode is 
activated. 

Using a list of procedures causes a step to be reported only if 
the step occurs in a specified procedure. 

You cannot specify both the PROCEDURE and MODULE 
parameters in the same SET_STEP_MODE subcommand. 

Omission causes $CURRENT to be used. 

SPAN or S 

Specifies how many steps must occur before execution stops 
and the step is reported. Omission causes Debug to report 
every step that occurs. 

COMMAND or COMMANDS or C 

String of subcommands that will be executed when the step 
occurs. If the subcommand string includes a RUN 
subcommand, the task is resumed and the step is not reported. 
If the string does not include a RUN subcommand, 
subcommand input is requested from the current Debug input 
file. 
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Example 


SET_STEP_MODE 


STATUS 

Optional SCL status variable in which the completion status 
of the subcommand is returned. If omitted and an error does 
not occur, Debug processes the next subcommand. If omitted 
and an error occurs, the status value is returned to 
$RESPONSE and to the Debug output file if $RESPONSE is 
connected to that file. This file is normally connected during 
interactive debugging. 

The following subcommands activate step mode with a unit of 
line in the current module, execute the entire program 
automatically, display each line executed, and then deactivate 
step mode. 

set_step_mode mode=on .. 

command= , display_debugging_environment .. 
display_options=ua; RUN* .. 
run 

set_step_»ode node=oft 
quit 
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DEBUG FUNCTIONS 


Debug Functions 

Debug functions are intended for use with SCL during a Debug session. 
These functions are only available while Debug has control. They are not 
known when your program is executing or after the Debug session has been 
terminated. 
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$CURRENT_LINE 


Purpose 


Format 

Example 


Returns the current line number value from the pr og ram aft 
the point where Debug has control. 

$CURRENT_LINE 

if $current_line < 100 then 
display_calls 
ifend 
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$CURRENT_MODULE 


Purpose 

Returns the name of the module where execution is stopped. 

Format 

$CURRENT_MODULE 


Example 

if $current_module= , main' 

then 


set_break name=break1 

line=234 


ifend 
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$CURRENT_PROCEDURE 


Purpose Returns the name of the procedure where execution is stopped. 

Format $CURRENT_PROCEDURE 

Example set_step_mode mode=on unit=procedure .. 

command 3 'if $current_procedure="sub2' 1 then; .. 
set_step_mode mode=on unit=line; .. 
else; run; ifend* 
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$CURRENT_PVA 


Purpose 


Format 

Example 


Returns an integer value for the process virtual address (PVA) 
where execution is stopped. 

$CURRENT_PVA 

if $current_pva > 0b03500000026(t6> then 
display_calls display_option=aU_calls 
ifend 
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$PROGRAM_ VALUE 


Purpose Returns the value of the program element that is specified as 
the name parameter. Additional parameters for module, 
procedure, recursion level, and recursion direction can be 
specified to fully identify the named variable. 

The $PROGRAM_ VALUE function allows you to incorporate 
the values of program variables in SCL statements in order to 
enhance debugging capabilities. 

Parameter values for functions are positional. Keywords such 
as NAME = are not recognized. Positional parameters cannot 
be selectively omitted unless no other parameter values are 
specified in the calling sequence. For instance, $PROGRAM_ 
VALUE (name,module) is valid, since all parameters up to the 
procedure parameter are specified. However, $PROGRAM_ 
VALUE (name„procedure) is not valid since the module 
parameter that is omitted is followed by a specified value for 
the procedure parameter. 

Format $PROG RAM _VALUE(name/nodu/e, procedure, 

recursion level,recursion direction ) 

Paramete r s name 

Name of the program element whose value is to be displayed. 
Specify one of the following: 

• Simple variable 

• Subscripted name 

• Field reference 

• Pointer reference 

The named variable must be used in your program. 

Because names can be long, SCL string variables can be used 
as aliases for them. To do this, assign the SCL variable to a 
string containing the identifier. Then use the SCL variable 
preceded by a question mark as the value of the name 
parameter. 

This parameter is required. 
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module 

Name of the module that contains the element specified by the 
name parameter. Omission causes the module executing when 
Debug gained control or the module specified by the 
CHANGE_DEFAULT subcommand to be used. 

procedure 

Name of the procedure that contains the element specified by 
the name parameter. If you specify a procedure that is not in 
the active call chain, its automatic variables cannot be used 
because it has no stack frame. Omission causes the procedure 
executing when Debug gained control to be used if a module 
name is not specified. Otherwise, there is no default procedure 
when a module name is specified and a procedure name is not 
specified; the element specified by the name parameter must 
exist at the module level. 

recursion _level 

The particular call of a recursive procedure to be used. Specify 
a positive integer greater than zero. If the recursion _ direction 
parameter specifies the keyword FORWARD, use a value of 1 
for the first call, 2 for the second call (the one called by the 
first call), and so on. If the recursion _ direction parameter 
specifies the keyword BACKWARD, use 1 for the most recent 
call, 2 for the predecessor, and so on. 

Omission causes 1 to be used. 
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Example 


recursion-direction 

Order in which calls to a recursive procedure are searched. It 
controls how the value of the recursion _ level parameter is 
interpreted. Specify one of the following keywords-’ 

FORWARD (F) 

If the recursion _ level parameter specifies 1, the first call to 
the procedure is used, a 2 specifies the second call, and so 
on. 

BACKWARD (B) 

If the recursion _level parameter specifies 1, the most 
recent call to the procedure is used, a 2 specifies its 
predecessor, and so on. 

Omission causes BACKWARD to be used. 

set_break name=b1 line=23 command^ .. 

'if $program_vaLue(index> < 45 then; run; ifend' 
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USING DEBUG 


Using Debug 

This section illustrates the use of Debug. Major Debug subcommands are 
illustrated in the sample Debug sessions. 


Sample Debus Sessions 

Debug can be used in interactive or batch mode. Two Debug sessions follow. 
The first session illustrates using Debug interactively. The second session 
illustrates using Debug in batch mode. 


Interactive Debug Session 

The source listing of the CYBIL program used in this interactive Debug 
session is shown in figure 9-1. 
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INTERACTIVE 


SOURCE LIST OF module_main J 

0 

1 

MODULE modute_main; 

0 

2 


0 

3 

PROCEDURE CXREF: p (operandl. 

0 

4 

operand2: integer; 

0 

5 

VAR result: integer; 

0 

6 

VAR status: boolean); 

0 

7 


0 

8 

PROGRAM main; 

0 

9 


0 

10 

VAR 

4 

11 

i/ 

4 

12 

)/ 

4 

13 

k: [STATIC] integer. 

4 

14 

X/ 

4 

15 

y. 

4 

16 

z: integer. 

4 

17 

b: boolean; 

4 

18 


4 

19 

i := 7ffffffffffffff(16); 

14 

20 

j := 10000000(16); 

1C 

21 

k := i * j; 

2A 

22 

k := i DIV j; 

38 

23 

FOR x : s 0 TO 100 DO 

42 

24 

y := x * x - 500; 

54 

25 

p (x, y, z, b); 

80 

26 

IF b THEN 

88 

27 

EXIT main; 

8A 

28 

IFEND; 

8A 

29 

FOREND; 

8E 

30 

PROCEND main; 

0 

31 

MODEND modulejnain; 


Figure 9-1. Source Listing for Interactive Debug Session 
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INTERACTIVE SESSION 


(Continued) 


SOURCE LIST 

OF m 

0 

1 

MODULE m; 

0 

2 


0 

3 

PROCEDURE CXDCL3 p (operandl. 

0 

4 

operand2: integer; 

0 

5 

VAR result: integer; 

0 

6 

VAR b: boolean); 

0 

7 


0 

8 

PROCEDURE CXREFD mult (a. 

4 

9 

b: integer; 

4 

10 

VAR c: integer); 

4 

11 


4 

12 

IF operandl < operand2 THEN 

10 

13 

mult (operandl, operand2, result); 

34 

14 

b := TRUE; 

3E 

15 

ELSE 

42 

16 

b := FALSE; 

4C 

17 

IFEND; 

4C 

18 

PROCEND p; 

0 

19 

MODEND m; 

SOURCE LIST OF perform_integer_multiplications 

0 

1 

MODULE perform_integer_multiplicat ions; 

0 

2 


0 

3 

PROCEDURE CXDCL3 mult (a. 

0 

4 

b: integer; 

0 

5 

VAR c: integer); 

0 

6 


0 

7 

c := a * b; 

16 

8 

PROCEND mult; 

0 

9 MODEND perform_integer_multiplications; 


Figure 9-1. Source Listing for Interactive Debug Session 
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INTERACTIVE SESSION 


The following command compiles the CYBIL program: 

/cybil i=sample l=list b=lgo lo=f da=all 

The name of the file containing the object code of the program is LGO. The 
following command initiates a Debug session: 

/execute_task file=lgo debug_mode=on 

Debug issues a banner and the Debug prompt, DB/, indicating that Debug 
has control. Entering the RUN subcommand initiates program execution: 

DEBUG 1.2 
DB/run 

— DOUG: arithuetic_overf low at M=module_main L=21 B0=12 
DB/ 

By looking at the source listing for MODULE MAIN, line 21, you can see 
that the overflow occurred during a multiplication operation. Entering the 
following subcommands allows you to view the values of the variables I and 

J: 


DB/display_program value name=i 
i = 576460752303423487 
OB/display_program value name=j 
j = 268435456 

When I and J are multiplied, the result exceeds the maximum value allowed; 
therefore, arithmetic overflow occurs. Since the P register points to the 
instruction that caused the overflow, entering the RUN subcommand would 
cause the overflow to reoccur. Changing the P register allows program 
execution to continue. The following subcommands accomplish this: 

D8/display_register kind=p 

P=8 04B 00000040 

DB/change_register kind=p value=0b04d00000042(16> 
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Since the value in the P register begins with a letter, a leading zero is 
required for the value parameter. Because the value parameter is in 
hexadecimal, the radix is required. The following subcommand shows that 
the P register is indeed changed: 

DB/display_register kind=p 
P=8 040 00000042 


The SET_STEP_MODE subcommand allows you to step through the 
execution of your program for a specified unit of stepping, as follows: 


DB/set_step_mode mode=on unit=line 
DB/run 

— DEBUG: step at M=modulejnain L=22 
DB/run 

— DEBUG: step at M=module_main L=23 
DB/run 

— DEBUG: step at M=module_main L=24 
DB/run 

— DEBUG: step at M=moduLejnain L=25 
DB/set_step_mode mode=off 


Setting the breaks shown next allows you to follow program execution: 


DB/set_break break=prog_main module=module_main line=26 
DB/set_break break=proc_p1 module=m procedure=p .. 

DB../byte_offset=4c(16) 

DB/set_break break=proc_p2 line=16 module=m 
DB/set_break moduLe=perform_integer_multiplications Line=7 
— Break name DB8$1 assigned to this break 

The first break set, PROG_MAIN, would not require the module/procedure 
parameters because it is for the module/procedure executing when Debug 
gained control. The address for the second break set, PROC_Pl, is specified 
in terms of module/procedure offset addressing; the hexadecimal offset is 
obtained from the first column of numbers on the source listing. (Since line 
tables were produced during compilation, and are available at execution, the 
break address is reported as a line number.) The third and fourth breaks set, 
PROC_P2 and DBB$1, require the module and procedure parameters since 
they are not set for the current module/procedure. Notice that you are not 
required to give a name to a break set. Debug assigns a name to the break if 
you do not specify a name. For example, in the fourth break shown in the 
preceding example, Debug assigned the name DBB$1. 
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Entering the RUN subcommand causes the program to execute until the first 
break is reached, as shown in the following example. The DISPLAY _ CALL 
subcommand allows you to trace program execution. The DISPLAY, 
OPTION parameter allows you to specify the type of traceback information 
you want to display. 

DB/run 

— DEBUG: break PR0C_P2, execution at M=m L=16 
DB/display_calIs dispLay_option=user_caLis 
— Traceback from procedure P module M at line 16 
— Called from procedure MAIN module MODULE_MAIN at line 25 
byte offset 44 

DB/display_calIs display_option=system_calIs 
— There are no system_calls on the stack frame. 

DB/run 

— DEBUG: break PROG_MAIN, execution at M=module_main L=26 
DB/display_calls 

— Traceback from procedure MAIN module MODULE_MAIN at 
line 26 
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At this point, you could enter any other subcommand. For example, you 
could enter the DISPLAY _STACK_FRAME subcommand and then the 
RUN subcommand: 


DB/display stack frame 


STACK FRAME 001 
00000000 00000000 
00000008 00000000 
00000010 304C0000 

00000018 00000000 
00000020 FFFFFFFF 

00000028 OOOOBOID 
00000030 0000604E 

00000038 00000000 

00000040 FFFFFFFF 

00000048 B04EOOOO 
00000050 B04EOOOO 

SAVE AREA 

P=B 04D OOOOOOAC 
UM=FFF7 UCR=0080 

A0=B 04E 000004DO 
A2=B 04E 00000430 
A4=B 04E 00000400 
A6=B 04E 000004AF 
A8=B 04E 00000442 
AA=B 04E OOOOOA88 
AC=F FFF 80000000 
AE=F FFF 80000000 


SEGMENT=04E 
00000000 
00000000 
OOCOFFFF OL 

00000000 
FFFFFEOC 

OOOD4A2E J. 

00000400 N 
00000000 
FFFFFEOC 

04A05D58 N DX 

04AF0430 N 0 


VMID=0 

MCR=0000 

A1=B 04E 00000478 
A3=B 04C 00000000 
A5=8 04B 00000020 
A7=B 04E 000004AF 
A9=B 04E 000006A0 
AB=F FFF 80000000 
AD=B 04E 000010D8 
AF=B 00B OOOOBB98 


XO=OOOOB04D 

00040254 

X1=OOOOFFFF 

80000000 

X2=OOOOFFFF 

80000000 

X3=00000000 

00000000 

X4=00000000 

00000064 

X5=FFFFFFFF 

FFFFFEOC 

X6=00000000 

00000000 

X7=00000000 

0000001D 

X8=00000000 

00000000 

X9=00000000 

00000008 

XA=00000000 

00000300 

XB=0000FFFF 

80000000 

XC=0000FFFF 

80000000 

XD=OOOOFFFF 

80000000 

XE=OOOOFFFF 

80000000 

XF=00000000 

00000008 

DB/run 

— DEBUG: 

break PR0C_P2 / 

execution at 

M=m L=16 
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Since CYBIL variable names can be long, you can assign an SCL variable to 
that name and then use the SCL variable prefixed by ? in a Debug 
subcommand. For example, the variable OPERAND1 in procedure P can be 
shortened to OP1 as follows: 

DB/op1='operand1' 

DB/display_program_value name=?op1 
operand1 = 1 

By looking at the source listing, you can see that the program is in a loop to 
be executed at the most 101 times. To avoid encountering the two breaks that 
are in the loop, you can delete them. First, you can display the break 
definitions to obtain the break names. Then delete them. Displaying the 
breaks again shows that two breaks were eliminated: 

DB/dispLay_breaks 

— Break PR0G_MAIN 

— eventCs) = execution 

— location: M=module_main L=26 

— Break PR0C_P1 

— event (s) = execution 

— location: H=m L=14 

— Break PR0C_P2 

— event(s) = execution 

— location: M=m L=16 

— Break D68$1 

— eventCs) = execution 

— location: M=perform_integer_multiplications L=7 
DB/delete_breaks break=(prog_main,proc_p2) 

DB/dispLay_breaks 

— Break PR0C_P1 

— event(s) = execution 

— location: M=m L=14 

— Break DBB$1 

— event(s) = execution 

— location: M=perform_integer_multiplications L=7 

Instead of entering two DELETE _BREAK subcommands, both breaks are 
specified in the same DELETE _BREAK subcommand. 
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When displaying the call chain, you can skip one or more of the most recent 
calls. 

OB/run 

— DEBUG: break DBB$1, execution at M=perform_integer_ 
multiplications L=7 
DB/display_calls 

— Traceback from procedure MULT module PERFORM_INTEGER_ 
MULTIPLICATIONS at line 7 

— Called from procedure P module M at line 13 byte 
offset 36 

— Called from procedure MAIN module MODULE_MAIN at line 25 
byte offset 44 
DB/display_calls start=2 

— Called from procedure P module M at line 13 byte offset 36 
— Called from procedure MAIN module MODULE_MAIN at line 25 
byte offset 44 
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Displaying values of program names is an important aspect of debugging. 

You can display the value of program names in other procedures/modules as 
well as in the current ones. All static values can be displayed. The value of a 
static variable can be displayed at any point of execution, but the value of 
an automatic variable can be displayed only when the procedure it belongs 
to is in the active call chain. To obtain the active call chain, enter the 
DISPLAY_CALLS subcommand as follows: 

DB/run 

— DEBUG: break PR0C_P1, execution at M=m L=14 
DB/display_calls 

— Traceback from procedure P module N at line 14 
— Called from procedure MAIN module NODULE_MAIN at line 25 
byte offset 44 

Procedures MAIN and P are active. You can, therefore, display the value of 
any variable within these procedures. To display the value of B in procedure 
P, enter the following subcommand: 

DB/di splay_program_value namc~b procedures 
b = FALSE 

To display the value of B in procedure MAIN, enter the following 

subcommand: 

DB/display_program_value name=b moduLe=module_main procedure=main 
b = FALSE 

Since module MODULE MAIN and procedure MAIN are not the current 
module and procedure, the MODULE and PROCEDURE parameters are 

required. 

Entering the RUN subcommand one more time causes the program to 
terminate. To terminate the Debug session, enter the QUIT subcommand as 

follows: 

DB/run 

— DOUG: program terminated by returning 
— DEBUG: The status at termination was: NORMAL. 

DB/quit 

— DEBUG: QUIT terminated task 

At this point, the operating system prompt, /, appears and you can enter 
any SCL command. 


Revision D 


The Debug Utility 9-91 • 



BATCH SESSION 


Batch Debug Session 

The source listing of the CYBIL program used in this batch Debug session is 
shown in figure 9-2. The name of the file containing the object code of the 
program is SAMPLE2. SAMPLE2 is essentially the same as the program 
used in the interactive session. The command stream used for the batch 
session is shown in figure 9-3. The Debug subcommands used are similar to 
those used in the interactive session. 


SOURCE 

LIST 

OF modulejnain 

0 

1 

MODULE modulejnain; 

0 

2 


0 

3 

PROCEDURE CXREFD p (operandl. 

0 

4 

operand2: integer; 

0 

5 

VAR result: integer; 

0 

6 

VAR status: boolean); 

0 

7 


0 

8 

PROGRAM main; 

0 

9 


0 

10 

VAR 

4 

11 

x. 

4 

12 

y. 

4 

13 

z: integer. 

4 

14 

b: boolean; 

4 

15 


4 

16 

FOR x := 0 TO 100 DO 

E 

17 

y := x * x - 500; 

20 

18 

p (x, y, z, b); 

4C 

19 

IF b THEN 

54 

20 

EXIT main; 

56 

21 

I FEND; 

56 

22 

F0REND; 

5A 

23 

PR0CEND main; 

0 

24 MODEND modulejnain; 


Figure 9-2. Source Listing for Batch Debug Session 

(Continued) 
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--—— ' 1 

SOURCE LIST OF m 

0 

1 

MODULE m; 

0 

2 


0 

3 

PROCEDURE CXDCL3 p (operandl. 

0 

4 

operand2: integer; 

0 

5 

VAR result: integer; 

0 

6 

VAR b: boolean); 

0 

7 


0 

8 

PROCEDURE CXREF: mult (a. 

4 

9 

b: integer; 

4 

10 

VAR c: integer); 

4 

11 


4 

12 

IF operandl < operand2 THEN 

10 

13 

mult (operandl, operand2, result); 

34 

14 

b := TRUE; 

3E 

15 

ELSE 

42 

16 

b := FALSE; 

4C 

17 

IFEND; 

4C 

18 

PROCEND p; 

0 

19 MODEND m; 

SOURCE LIST OF perform_integer_multiplications 

0 

1 

MODULE perform_integer_muImplications; 

0 

2 


0 

3 

PROCEDURE CXDCL3 mult (a. 

0 

4 

b: integer; 

0 

5 

VAR c: integer); 

0 

6 


0 

7 

c := a * b; 

16 

8 

PROCEND mutt; 

0 

9 MODEND perform_integer_multiplications; 


Figure 9-2. Source Listing for Batch Debug Session 
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The following numbered paragraphs correspond to the numbers in figure 9-X 

(I) The COLLECT _TEXT command collects the Debug subcommands 
on the file named BATCH_SESSION. All subcommands are placed 
on BATCH_SESSION until the double asterisks are encountered. 

© The CREATE _VARIABLE command creates an SCL variable of 
type STATUS to be used on the Debug SET_BREAK subcommands. 

(3) The IF/IFEND command is used to check the status variable. If the 
status variable is not provided and the subcommand is in error, the 
session will be terminated. 

© Indicates that subcommands are no longer collected on the file 
BATCH_SESSION. 

(5) The four CREATE_FILE_CONNECTION commands cause a 

complete record of the Debug session to be recorded on file SESSION. 

© The EXECUTE _TASK command initiates the Debug session. Notice 
that the Debug input file is BATCH _SESSION. 

© The standard file $OUTPUT must be disconnected from SESSION 
before that file can be copied. 

(8) The COPY_FILE command causes the file SESSION to be copied to 
file $OUTPUT, which is printed at the end of the job. The contents of 
this file are shown in figure 9-4. Notice that the Debug prompt, DB/, 
is replaced by Cl or CS because of the file connections. 


9-94 


CYBIL Language Definition 


Revision C 




BATCH SESSION 


login family name=... user=... passwords., job class=batch 
© collect_text output=batch_session 
(?) create_variable name=stat kind=status 

set_break break=prog_main line=26 module=module_main status=stat 
© if stat.normal = false then; 

display_value 'break prog_main failed' 
ifend 

set_break break=proc_p1 line=14 module=m status=stat 

if stat.normal = false then; display_value 'break proc_p1 failed' 

ifend 

set_break break=proc_p2 line=16 module=m status=stat 

if stat.normal = false then; display_value 'break proc_p2 failed' 

ifend 

set_break break=proc_mult Line=7 .. 

module=perform_integer_multiplications status=stat 

if stat.normal = false then; 

display_value 'break proc_mult failed' 

ifend 

run 

display_calIs display_option=user_calIs 
display_calls display_option=system_ca Lls 
run 

display_calls 

display_stack_frame 

run 

display_breaks 

delete_breaks break=(prog_main,proc_p2) 

display_breaks 

run 

display_calls 
display_calls start=2 
run 

display_calls 

display_program_value name=b procedure=p 

display_program_value name=b module=module_main procedure=main 
run 
quit 
© ** 

attach_file file=sample2 
(f) create_file_connection Soutput session 
create_file_connection Sresponse session 
create_file_connection Serrors session 
create_file_connection Secho session 
@ execute_task file=sample2 debug_input=batch_session .. 

debug_output=session debug_mode=on 
© delete_file_connection Soutput session 
© copy_file session 
logout 


Figure 9-3. Command Stream for Batch Debug Session 
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Cl execute_task file=sample2 debug_input=batch_session 
debug_output=session debug_mode=on 

debug” 

Cl create_variable name=stat kind=status 

Cl set_break break=prog_main line=26 module=module_main status=stat 
Cl if stat.normal = false then 
CS display_value 'break progjnain failed' 

CS ifend 

Cl set_break break=proc_p1 line=14 module=m status=stat 
Cl if stat.normal = false then 
CS display_value 'break proc_p1 failed' 

CS ifend 

Cl set_break break=proc_p2 line=16 module=m status=stat 
Cl if stat.normal = false then 
CS display_value 'break proc_p2 failed' 

CS ifend 

Cl set_break break=proc_mult line=7 
module=perform_integer_multiplications status=stat 
Cl if stat.normal = false then 
CS display_value 'break proc_mult failed' 

CS ifend 
Cl run 

— DEBUG: break PR0C_P2, execution at M=m L=16 
Cl display_calls display_option=user_calls 

-- Traceback from procedure P module M at line 16 

— Called from procedure MAIN module MODULE_MAIN at line 25 byte 
offset 44 

Cl display_calls display_option=system_calls 

— There are no system_calls on the stack frame. 

Cl run 

— DEBUG: break PROG_MAIN, execution at M=module_main L=26 
Cl display_calls 

— Traceback from procedure MAIN module MODULE_MAIN at line 26 


Figure 9-4. Batch Debug Session 


(Continued) 
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Cl display_stack_frame 

STACK FRAME 001 

SEGMENT=035 

00000000 00000000 

00000000 

00000008 00000000 

00000000 

00000010 00006034 

00000000 4 

00000018 00000000 

00000000 

00000020 FFFFFFFF 

FFFFFEOC 

00000028 00006035 

00000398 5 

00000030 00000000 

00000000 

00000038 00000000 

00000000 

00000040 FFFFFFFF 

FFFFFEOC 

00000048 B0350000 

04084834 5 H4 

00000050 B0350000 

04170428 5 ( 

SAVE AREA 

P=8 034 0000004C 

VWID=0 

UM=FFF7 UCR=0080 

MCR=0000 

A0=8 035 00000438 

A1=B 035 000003EO 

A2=8 035 00000398 

A3=8 033 00000000 

A4=8 035 00000370 

A5=8 035 00000417 

A6=B 035 00000417 

A7=8 035 00000250 

A8=B 033 00000080 

A9=8 011 00000408 

AA=8 011 00000168 

AB=B 011 00000608 

AC=8 006 00021A10 

AD=B 006 000029AO 

AE=F FFF 80000000 

AF=B 035 00000398 


Figure 9-4. Batch Debug Session 
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XO0000B034 00040243 X1=0000B035 00000398 

X2=00000000 00000000 X3=00000000 00000064 

X4=FFFFFFFF FFFFFEOC X5=00000000 00000000 

X6=00000000 OOOOOOOF X7=00000000 00989680 

X8=00000000 00000022 X9=00000000 00000012 

XA=00000000 0000004E XB=00000000 00000000 

XC=00000000 000004CC XD=00000000 00000003 

XE=00000000 00000751 XF=00000000 00000000 

Cl run 

— DEBUG: break PR0C_P2, execution at M=m L=16 
Cl di splay ..breaks 
— Break PROG_MAIN 

— event(s) * execution 

— location: M=module_main L=26 
— Break PR0C_P1 

— event(s) = execution 

— location: M=m L=14 
— Break PR0C_P2 

— event(s) = execution 

— location: M=m L=16 
— Break PROCJHJLT 
-- event(s) = execution 

— location: M=perform_integer_multiplications L=7 
Cl delete_breaks break=Cprog_main,proc_p2) 

Cl di splay ..breaks 
~ Break PR0C_P1 

— event(s) = execution 

— location: M=m L=14 
~ Break PR0C_MULT 

— event(s) = execution 

— location: M=perform_integer_multiplications L=7 
Figure 9-4. Batch Debug Session 

(Continued) 
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(Continued) 

Cl run 

— DEBUG: break PR0C_MULT, execution at 
M=perform_integer_muItiplications L=7 
Cl display_caLls 

— Traceback from procedure MULT module 
PERFORM_INTEGER_MULTIPLICATIONS at line 7 
— Called from procedure P module M at line 13 byte offset 36 
— Called from procedure MAIN module MODULE_MAIN at line 25 byte 
offset 44 

Cl display_calls start=2 

— Called from procedure P module M at line 13 byte offset 36 
— Called from procedure MAIN module MODULE_MAIN at line 25 byte 
offset 44 
Cl run 

— DEBUG: break PR0C_P1, execution at M=m L=14 
Cl display_calls 

— Traceback from procedure P module M at line 14 
— Called from procedure MAIN module MODULE_MAIN at Line 25 byte 
offset 44 

Cl display_program_value name=b procedure=p 
b = FALSE 

Cl display_program_value name=b module=modulejnain procedure=main 
b = FALSE 
Cl run 

— DEBUG: program terminated by returning 
— DEBUG: The status at termination was: NORMAL. 

Cl quit 

— DEBUG: QUIT terminated task 
Cl delete_file_connection Soutput session 
Cl copy_file session 
EOI ENCOUNTERED. 


Figure 9-4. Batch Debug Session 
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A 


A_ 

Access Attribute 

Characteristic of a variable that determines whether the variable can be 
both read and written. Specifying the access attribute READ makes the 
variable a read-only variable. 

Active Call Chain 

List of calls that led to the current procedure. 

Alphabetic Character 

One of the following letters: 

A through Z 
a through z 

See also Character and Alphanumeric Character. 

Alphanumeric Character 

Alphabetic character or a digit. See also Character, Alphabetic Character, 
and Digit. 

Assignment Statement 

A statement that assigns a value to a variable. 
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B_ 

Batch Debugging 

Debugging when the user has no direct control of debugging during 
program execution. Contrast with Interactive Debugging. 

Bit 

Binary digit. A bit has the value 0 or 1. See also Byte. 

Boolean 

A kind of value that is evaluated as TRUE or FALSE. 

Break 

The primary mechanism for Debug to gain control from an executing 
program. A break specifies an event and an address range such that when 
the event occurs within the address range, Debug takes control. 

Byte 

A group of bits. For NOS/VE, one byte is equal to 8 bits. An ASCII 
character code uses the rightmost 7 bits of one byte. 

Byte Offset 

A number corresponding to the number of bytes beyond the beginning of 
a line, procedure, module, or section. 
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c_ 

Character 

Letter, digit, space, or symbol that is represented by a code in one or more 
of the standard character sets. 

It is also referred to as a byte when used as a unit of measure to specify 
block length, record length, and so forth. 

A character can be a graphic character or a control character. A graphic 
character is printable; a control character is nonprintable and is used to 
control an input or output operation. 

Character Constant 

A fixed value that represents a single character. 

Comment 

Any character or sequence of characters that is preceded by an opening 
brace and terminated by a closing brace or an end of line. A comment is 
treated exactly as a space. 

Compilation Time 

The time at which a source program is translated by the compiler to an 
object program that can be loaded and executed. Contrast with Execution 
lime. 

Compiler 

A processor that accepts source code as input and generates object code as 
output 

Condition Handler 

A procedure called when an exception condition occurs. Condition handler 
processing occurs after Debug processing if Debug mode is on. The 
procedure is called only if it has been established as the condition handler 
for the condition type and the condition occurs within its scope. 
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D_ 

Delimiter 

The indicator that separates and organizes data. 

Digit 

One of the following characters: 

0123456789 


E______ 

Entry Point 

The point in a module at which execution of the module can begin. 

Event 

A condition, such as division by zero, that causes Debug to gain control. 
Execution Ring 

The level of hardware protection assigned to a procedure while it is 
executing. 

Execution Time 

The time at which a compiled source program is executed. Also known as 
Run Time. 

Expression 

Notation that represents a value. A constant or variable appearing alone, 
or combinations of constants, variables, and operators. 

External Reference 

Call to an entry point in another module. 


Field 

A subdivision of a record that is referenced by name. For example, the 
field NORMAL in a record named OLD .STATUS is referenced as 
follows: 

OLD.STATUS.NORMAL 


A-4 CYBIL Language Definition 


Revision D 


GLOSSARY 


Integer Constant 

One or more digits and, for hexadecimal integer constants, the following 
characters: 

ABCDEFabcdef 

A hexadecimal integer constant must begin with a digit. A preceding sign 
and subsequent radix are optional. 

Interactive Debugging 

Debugging when the user has direct control of the debugging process. 
Contrast with Batch Debugging. 


L_ 

Load Module 

A module reformatted for code sharing and efficient loading. When the 
user generates an object library, each object module in the module list is 
reformatted and written as a load module on the object library. 


M_ 

Machine Addressing 

Use of actual machine addresses. Contrast with Module Addressing and 
Symbolic Addressing. 

Machine-Level Debugging 

Debugging using machine-level terms such as machine addresses. A 
knowledge of machine architecture is required. Contrast with Symbolic 

Debugging. 

Module 

Unit of text accepted as input by the loader, linker, or object library 
generator. See also Object Module and Load Module. 

Module Addressing 

Use of addresses in terms of module and procedure names and an offset. 
Contrast with Machine Addressing and Symbolic Addressing. 
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N_ 

Name 

Combination of from 1 through 31 characters chosen from the following 
set: 

• Alphabetic characters (A through Z and a through z). 

• Digits (0 through 9). 

• Special characters (#, $, and _). 

The first character of a name cannot be a digit. 


O_ 

Object Code 

Executable code produced by a compiler. 

Object Module 

Compiler-generated unit containing object code and instructions for 
loading the object code. It is accepted as input by the system loader and 
the object library generator. 
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Page 

An allocatable unit of real memory. 

Pointer 

The virtual address of a value. 


R_ 

Range 

Value represented as two values separated by an ellipsis. The element is 
associated with the values from the first value through the second value. 
The first value must be less than or equal to the second value. For 
example: 

1 .. 100 

Reserved Word 

Word that has a predefined meaning in a language. The user cannot 
define a new meaning or use for a reserved word. 

Ring 

Level of hardware protection given a file or segment. A file is protected 
from unauthorized access by tasks executing in higher rings. See also 
Execution Ring. 

Ron Time 

See Execution Time. 
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s_ 

Section 

A storage area that contains variables with common access attributes (for 
example, read-only variables or read/write variables). 

Segment 

One or more pages assigned to a file. The segment has the ring attributes 
of the file. 

Source Code 

Statements written for input to a compiler. 

Statement List 

One or more statements separated by delimiters. 

String Constant 

Sequence of characters delimited by apostrophes (’). An apostrophe can be 
included in the string by specifying two consecutive apostrophes. 

Symbolic Addressing 

Use of addresses in source program terms such as program names and 
line numbers. Contrast with Machine Addressing and Module 
Addressing. 

Symbolic Debugging 

Debugging using source program terms such as line numbers and 
program names. Contrast with Machine-Level Debugging. 


T_ 

Traceback 

A list of procedure names within a program, beginning with the currently 
executing procedure, proceeding backward through the sequence of called 
procedures, and ending with the main program. 
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GLOSSARY 


V_ 

Variable 

Represents a data value. 

Variable Attribute 

Characteristic of a variable. 
See also Access Attribute. 
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Character Set 


B 


Table B-l lists the ASCII character set. 

NOS/VE supports the American National Standards Institute (ANSI) 
standard ASCII character set (ANSI X3.4-1977). NOS/VE represents each 7- 
bit ASCII code in an 8-bit byte. The 7 bits are right-justified in each byte. For 
ASCII characters, the leftmost bit is always zero. 

In addition to the 128 ASCII characters, NOS/VE allows use of the leftmost 
bit in an 8-bit byte for 256 characters. The use and interpretation of the 
additional 128 characters is user-defined. 
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CHARACTER SET 


Table B-l. ASCII Character Set 



ASCII Code 


Graphic or 
Mnemonic 

Name or Meaning 

Decimal 

Hexadecimal 

Octal 

000 

00 

000 

NUL 

Null 

001 

01 

001 

SOH 

Start of heading 

002 

02 

002 

STX 

Start of text 

003 

03 

003 

ETX 

End of text 

004 

04 

004 

EOT 

End of transmission 

005 

05 

005 

ENQ 

Enquiry 

006 

06 

006 

ACK 

Acknowledge 

007 

07 

007 

BEL 

Bell 

008 

08 

010 

BS 

Backspace 

009 

09 

Oil 

HT 

Horizontal tabulation 

010 

OA 

012 

LF 

Line feed 

Oil 

0B 

013 

VT 

Vertical tabulation 

012 

OC 

014 

FF 

Form feed 

013 

OD 

015 

CR 

Carriage return 

014 

OE 

016 

SO 

Shift out 

015 

OF 

017 

SI 

Shift in 

016 

10 

020 

DLE 

Data link escape 

017 

11 

021 

DC1 

Device control 1 

018 

12 

022 

DC2 

Device control 2 

019 

13 

023 

DC3 

Device control 3 

020 

14 

024 

DC4 

Device control 4 

021 

15 

025 

NAK 

Negative acknowledge 

022 

16 

026 

SYN 

Synchronous idle 

023 

17 

027 

ETB 

End of transmission block 

024 

18 

030 

CAN 

Cancel 

025 

19 

031 

EM 

End of medium 

026 

1A 

032 

SUB 

Substitute 

027 

IB 

033 

ESC 

Escape 

028 

1C 

034 

FS 

File separator 

029 

ID 

035 

GS 

Group separator 

030 

IE 

036 

RS 

Record separator 

031 

IF 

037 

US 

Unit separator 

032 

20 

040 

SP 

Space 

033 

21 

041 

J 

Exclamation point 

034 

22 

042 

” 

Quotation marks 

035 

23 

043 

# 

Number sign 

036 

24 

044 

$ 

Dollar sign 

037 

25 

045 

% 

Percent sign 

038 

26 

046 

& 

Ampersand 

039 

27 

047 

9 

Apostrophe 

040 

28 

050 

( 

Opening parenthesis 

041 

29 

051 

) 

Closing parenthesis 

042 

2A 

052 

* 

Asterisk 

043 

2B 

053 

+ 

Plus 

044 

2C 

054 


Comma 

045 

2D 

055 

- 

Hyphen 

046 

2E 

056 


Period 

047 

2F 

057 

/ 

Slant 
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Table B-l. ASCII Character Set (Continued) 



ASCII Code 


Graphic or 
Mnemonic 

Name or Meaning 

Decimal 

Hexadecimal 

Octal 

048 

30 

060 

0 

Zero 

049 

31 

061 

1 

One 

050 

32 

062 

2 

Two 

051 

33 

063 

3 

Three 

052 

34 

064 

4 

Four 

053 

35 

065 

5 

Five 

054 

36 

066 

6 

Six 

055 

37 

067 

7 

Seven 

056 

38 

070 

8 

Eight 

057 

39 

071 

9 

Nine 

058 

3A 

072 


Colon 

059 

3B 

073 

; 

Semicolon 

060 

3C 

074 

< 

Less than 

061 

3D 

075 

= 

Equals 

062 

3E 

076 

> 

Greater than 

063 

3F 

077 

9 

Question mark 

064 

40 

100 

@ 

Commercial at 

065 

41 

101 

A 

Uppercase A 

066 

42 

102 

B 

Uppercase B 

067 

43 

103 

C 

Uppercase C 

068 

44 

104 

D 

Uppercase D 

069 

45 

105 

E 

Uppercase E 

070 

46 

106 

F 

Uppercase F 

071 

47 

107 

G 

Uppercase G 

072 

48 

110 

H 

Uppercase H 

073 

49 

111 

I 

Uppercase I 

074 

4A 

112 

J 

Uppercase J 

075 

4B 

113 

K 

Uppercase K 

076 

4C 

114 

L 

Uppercase L 

077 

4D 

115 

M 

Uppercase M 

078 

4E 

116 

N 

Uppercase N 

079 

4F 

117 

O 

Uppercase O 

080 

50 

120 

P 

Uppercase P 

081 

51 

121 

Q 

Uppercase Q 

082 

52 

122 

R 

Uppercase R 

083 

53 

123 

S 

Uppercase S 

084 

54 

124 

T 

Uppercase T 

085 

55 

125 

U 

Uppercase U 

086 

56 

126 

V 

Uppercase V 

087 

57 

127 

w 

Uppercase W 

088 

58 

130 

X 

Uppercase X 

089 

59 

131 

Y 

Uppercase Y 

090 

5A 

132 

Z 

Uppercase Z 

091 

5B 

133 

[ 

Opening bracket 


(Continued) 
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Table B-l. ASCII Character Set (Continued) 



ASCII Code 


Graphic or 
Mnemonic 

Name or Meaning 

Decimal 

Hexadecimal 

Octal 

092 

5C 

134 

\ 

Reverse slant 

093 

5D 

135 

i 

Closing bracket 

094 

5E 

136 


Circumflex 

095 

5F 

137 

- 

Underline 

096 

60 

140 

' 

Grave accent 

097 

61 

141 

a 

Lowercase a 

098 

62 

142 

b 

Lowercase b 

099 

63 

143 

c 

Lowercase c 

100 

64 

144 

d 

Lowercase d 

101 

65 

145 

e 

Lowercase e 

102 

66 

146 

t 

Lowercase f 

103 

67 

147 

g 

Lowercase g 

104 

68 

150 

h 

Lowercase h 

105 

69 

151 

i 

Lowercase i 

106 

6A 

152 

j 

Lowercase j 

107 

6B 

153 

k 

Lowercase k 

108 

6C 

154 

i 

Lowercase 1 

109 

61) 

155 

m 

Lowercase m 

110 

6E 

156 

n 

Lowercase n 

111 

6F 

157 

o 

Lowercase o 

112 

70 

160 

p 

Lowercase p 

113 

71 

161 

q 

Lowercase q 

114 

72 

162 

r 

Lowercase r 

115 

73 

163 

s 

Lowercase s 

116 

74 

164 

t 

Lowercase t 

117 

75 

165 

u 

Lowercase u 

118 

76 

166 

V 

Lowercase v 

119 

77 

167 

w 

Lowercase w 

120 

78 

170 

X 

Lowercase x 

121 

79 

171 

y 

Lowercase y 

122 

7A 

172 

z 

Lowercase z 

123 

7B 

173 

f 

Opening brace 

124 

7C 

174 

1 

Vertical line 

125 

7D 

175 

1 

Closing brace 

126 

7E 

176 


Tilde 

127 

7F 

177 

DEL 

Delete 
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The reserved words in CYBIL are listed next. 


ALIAS 

LIST ALL 

ALIGNED 

LISTCTS 

ALLOCATE 

LISTEXT 

AND 

LISTOBJ 

ARRAY 

LOWERBOUND 

BEGIN 

LOWERVALUE 

BOOLEAN 

MOD 

BOUND 

MODEND 

CASE 

MODULE 

CASEND 

NEWTITLE 

CAT 

NEXT 

CELL 

NIL 

CHAR 

NOCOMPILE 

CHKALL 

NOT 

CHKNIL 

OF 

CHKRNG 

OFF 

CHKSUB 

OLDTITLE 

CHKTAG 

ON 

CHR 

OR 

COMMENT 

ORD 

COMPILE 

PACKED 

CONST 

POP 

CYCLE 

PRED 

DIV 

PROCEDURE 

DO 

PROCEND 

DOWNTO 

PROGRAM 

EJECT 

PUSH 

ELSE 

READ 

ELSEIF 

REAL 

END 

RECEND 

EXIT 

RECORD 

FALSE 

REL 

FOR 

REP 

FOREND 

REPEAT 

FREE 

RESET 

FUNCEND 

RETURN 

FUNCTION 

RIGHT 

HEAP 

SECTION 

IF 

SEQ 

IFEND 

SET 

IN 

SKIP 

INLINE 

SPACING 

INTEGER 

STATIC 

LEFT 

STRING 

LIST 

STRLENGTH 
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SUCC 

THEN 

TITLE 

TO 

TRUE 

TYPE 

UNTIL 

UPPERBOUND 

UPPERVALUE 

VAR 

WHILE 

WHILEND 

WRITE 

XDCL 

XOR 

XREF 

#ADDRESS 

#CALLER_ID 

#COMPARE _ SWAP 

#CONVERT_POINTER_TO_PROCEDU 

#FREE_RUNNING_CLOCK 

#GATE 

#HASH_SVA 

#INLINE 

#KEYPOINT 

#LOC 

#OFFSET 

#PRE VIOUS _ S A VE _ ARE A 
#PTR 

#PURGE_BUFFER 

#RE AD _ REGISTER 

#REL 

#RING 

#SCAN 

#SEGMENT 

#SEQ 

#SIZE 

#TRANSLATE 

#UNCHECKED_CON VERSION 

#WRITE_ REGISTER 

$CHAR 

$INTEGER 

SREAL 
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Data Representation in Memory D 


Memory is made up of 8-bit addressable bytes with eight bytes to one 64-bit 
word. (An 8-bit byte is synonymous with a cell.) Table D-l summarizes how 
different data types are represented in memory. The data under the heading 
Alignment specifies how a variable of the data type is stored in packed and 
unpacked format. The word ’’byte” means a variable is stored in the first 
available byte; ’’bit” means it is stored in the first available bit. 


Table D-l. Data Representation in Memory 


Alignment 


Type 

Size 

Unpacked 

Packed 

Integer 

8 bytes 

Byte 

Byte 

Character 

1 byte 

Byte 

Bit 

Boolean 

1 bit 

Right-justified 
in a byte 

Bit 

Ordinal 

As needed 
for components 

Right-justified 
in a byte 

Bit 

Subrange 

As needed 
for components 

Right-justified 
in a byte 

Bit 

Real 

8 bytes 

Byte 

Byte 

Cell 

Byte 

Byte 

Byte 

Fixed pointer 

6 bytes 

Byte 

Byte 

Fixed relative 
pointer 

4 bytes 

Byte 

Byte 

String 

1 byte for 
each character 

Byte 

Byte 

Array/ 

Record 

Depends on 
type of 
components 

Byte 

Components are 
un aligned 

Set 

As needed 
for components 

Right-justified 
in a byte 

Bit if <57 
components; 
byte if > 57 
components 
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DATA REPRESENTATION IN MEMORY 


The following examples show how a record would look in memory in various 
formats: first unpacked, then packed, packed with some positioning changes, 
and finally aligned. The memory shown here is in 8-byte words, but because 
bytes can be addressed individually, it’s possible the record could start at any 
byte (if it is not aligned otherwise). 

The unpacked record is: 

TYPE 

table = record 
name: string(7), 
file: (bi, di, Ig, pr), 
number_of_accesses: integer, 
users: 0 .. 100, 
ptr_iotype: “iotype, 
b: boolean, 
recend; 

This record would appear in memory as follows (slashes indicate unused 
memory): 


FILE - 

Byte 0 Byte 1 Byte 2 Byte 3 Byte 4 Byte 5 Byte 6 Byte 7 


Character 

Character 

NAME 

Character j Character j Character 

Character 

Character 


B 

_ 

_ 

NUMBER OF ACCESSES 

_1_IT_1_ 



i 

USERS 

PTR IOTYPE 

_1_1_11_ 




B 
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DATA REPRESENTATION IN MEMORY 


The packed record is: 

TYPE 

table = packed record 
name: string(7), 
file: (bi, di, Ig, pr), 
number_of_accesses: integer, 
users: 0 .. 100, 
ptr_iotype: "iotype, 
b: boolean, 
recend; 

This record would appear in memory as follows (slashes indicate unused 
memory): 


FILE 


Byte 0 Byte 1 Byte 2 Byte 3 Byte 4 Byte 5 Byte 6 \ Byte 7 


Character 

NAME 

| Character | Character | Character | Character 

Character | Character 

T 

if 


NUMBER OF ACCESSES 

1_1_1_If_1_1_1 


USERS 

1 

PTR 1 

1 1 "1 

OTYPE 

1_1_1_ 

B 

n 
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DATA REPRESENTATION IN MEMORY 


The record, as follows, is now rearranged slightly to make more efficient use 
of the space: 

TYPE 

table = packed record 
name: string(7), 
file: (bi, di, Ig, pr), 
number_of_accesses: integer, 
users: 0 .. 100, 
b: boolean, 
ptr_iotype: “iotype, 
recend; 

This record would appear in memory as follows (slashes indicate unused 
memory): 


r-FILE 

Byte 0 Byte 1 Byte 2 Byte 3 Byte 4 Byte 5 Byte 6 \ Byte 7 


Character 

Character 

NAME 

Character j Character j Character 

Character 

Character 

T 



NUMBER OF ACCESSES 

_1_1_IT_1_ 



USERS 

B 


PTR IOTYPE 

_I_IL_. J 

_ 


i§ 
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DATA REPRESENTATION IN MEMORY 


The following record declares the pointer field to be aligned at byte zero (the 
first byte) of a word-' 

TYPE 

table = packed record 
name: string(7), 
file: (bi, di, Ig, pr), 
number_of_accesses: integer, 
users: 0 .. 100, 
b: boolean, 

ptr_iotype: ALIGNED CO MOD 80 ‘iotype, 
recend; 

This record would appear in memory as follows (slashes indicate unused 
memory): 
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Index 


A 

A registers 
Change 9-32 
Display 9-51 

ABORT_FILE attribute 9-4 
Access attribute 3-6; A-l 
Accessing Debug 

During program execution 9-3 
When a program fails 94 
Active call chain A-l 
Active segment identifier 7-22 
Actual parameters 
Function 6-19,21 
Procedure 7-11,13 
Program 2-13 
Adaptable array 
Definition 443 
Example 5-34 
Format 443 
Size 5-33 
Adaptable heap 
Definition 447 
Format 447 
Size 5-33 

Adaptable pointer size 5-33 
Adaptable record 
Definition 444 
Format 444 
Size 5-33 

Adaptable sequence 
Definition 446 
Example 5-34 
Format 446 
Size 5-33 
Adaptable string 
Definition 442 
Format 442 
Size 5-33 
Adaptable types 
Definition 442 
Equivalent 4-2 
Example 5-34 
Pointers to 4-15 


Addition operation 5-5 
Addition operators 54 
#ADDRESS function 6-23 
Addressing 

Bound modules 9-13 
Debug 9-8 
Machine A-5 
Module A-5 
Symbolic A-8 

Advance page directive 8-20 
Alias name 2-10,12; 3-3; 6-17; 7-9 
ALIGNED 

parameter 4-29,31,37,44 
Alignment 

Examples D-2 
Of elements in memory D-l 
Parameter 4-29,31,37,44 
ALLOCATE statement 
Definition 5-38 
Example 5-34 
Format 5-38 

Alphabetic character A-l 
Alphanumeric character A-l 
AND operator 5-3 
ARITHMETIC. OVERFLOW 
break 9-60 

ARITHMETIC. SIGNIFICANCE 
break 9-61 
Array 

Adaptable 443 
Definition 4-24 
Elements 4-26 
Examples 4-26,27 
Format 4-24 

Initializing elements 4-25 
LOWERBOUND function 6-5 
Referencing elements 4-25 
Size 4-24 

Subscript bounds 4-24 
Two-dimensional 4-26 
UPPERBOUND function 6-15 
ASCII character set B-l 
ASID, see active segment identifier 
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Assigning 

Elements of a set 4-38 
Strings 4-23 

Assignment operator 5-15 
Assignment, set 4-38 
Assignment statement 
Compile-time 8-10 
Definition 5-13; A-l 
Format 5-13 
Attribute(s) 

Access 3-6 
Debug 9-3,4 

Effect on initialization by 3-14 

Function 6-17 

#GATE 3-4 

List 8-2 

Procedure 7-9 

READ 3-3,6 

Scope 3-7 

Section name 34,11 
STATIC 2-9; 34,9 
Storage 3-9 
XDCL 2-9; 3-3,7 
XREF 3-3,7 

Automatic variable 2-9; 3-9 

B 

Basic types 4-3 
Batch Debug 
Definition A-2 
Example 9-92 
BEGIN statement 
Definition 5-16 
Format 5-16 

Binary object code, listing 8-2 
$BINDING section 3-11 
Bit A-2 

Blanks in syntax 2-6 
Blocks 2-8 
Boolean 

Constant 24 
Definition 4-6; A-2 
Difference 5-5 
Example 4-6 
Format 4-6 
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Bound module 
addressing 9-13 
BOUND parameter 4-31 
Bound variant record 
Definition 4-33 
Equivalent 4-2 
Tag field size 5-33 
BRANCH break 9-61 
Break report message 9-9 
Breaks, Debug 

Definition 9-8; A-2 
Delete 9-35 
Display 9-36 
Set 9-60 
Byte A-2 

Byte offset 6-23,25; A-2 

C 

Cache, purging 7-22 
CALL break 9-61 
Call chain. Debug 9-38 
Caller id 7-15 

#CALLER_ ID procedure 7-15 
Calling 

Function 6-21 
Procedure 7-13 
CALLREL instruction 7-15 
CALLSEG instruction 7-15 
CASE statement 
Definition 5-26 
Examples 5-27 
Format 5-26 
CASEND 5-26 
CAT 2-5; 4-23 
Cell 

Definition 4-12 
Format of type 4-12 
Pointer to 4-17 
Type 4-12 

CHAD subcommand 9-22 
CHAM subcommand 9-25 
CHANGE_DEFAULT 
subcommand 9-22 
CHANGE^ MEMORY 
subcommand 9-25 
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INDEX 


CHANGE_PROGRAM_ VALUE 
subcommand 9-28 
CHANGE_REGISTER 
subcommand 9-32 
CHAPV subcommand 9-28 
$CHAR function 6-2 
CHAR subcommand 9-32 
Character 

Alphabetic A-l 
Alphanumeric A-l 
Constant 2-3; A-3 
Definition 4-5; A-3 
Example 4-5 
Format 4-5 
Valid 2-1 
Character set B-l 
CHKALL toggle 8-15 
CHKNIL toggle 8-15 
CHKRNG toggle 8-15 
CHKSUB toggle 8-15 
CMPXA instruction 7-17 
Coefficient 24 
COMMAND file 9-5 
Comment control directive 8-28 
COMMENT directive 8-28 
Comments 2-7; A-3 
#COMP ARE _ SW AP 
procedure 7-17 
Comparing strings 4-23 
Compilation 
Call 8-1 

Declarations 8-8 
Listing 8-1 
Statements 8-8 
Time A-3 

COMPILE directive 8-26 
Compile-time 

Assignment statement 8-10 
Directives 8-12 
Expressions 8-9 
IF statement 8-11 
Variables 8-8 
Compiler 

Checking of subranges 4-9 
Definition A-3 
Complement operation 5-11 
Complement, set 54 
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Component type 4-18 
Concatenation 2-5; 4-23 
Condition code, Debug 9-7 
CONDITION field 9-7 
Condition handler 
Debugging 9-14 
Definition A-3 
CONST format 3-1 
Constant 
Boolean 24 
Character 2-3 
Declaration 3-1 
Definition 2-3 
Examples 3-2 
Expression 2-6 
Floating-point 24 
Format 3-1 
Integer 2-3 
Ordinal 24 
Pointer 24 
Real 24 
String 2-5 
Control statements 
CASE 5-26 
CYCLE 5-28 
EXIT 5-30 
IF 5-24 
Overview 5-23 
RETURN 5-31 
Conventions 8 

#CONVERT_POINTER_TO_ 
PROCEDURE procedure 7-19 
CPYSX instruction 6-27 
CPYXS instruction 7-28 
$CURRENT_ LINE function 9-75 
$CURRENT_ MODULE 
function 9-76 

$CURRENT_PROCEDURE 
function 9-77 

$CURRENT_PVA function 9-78 
CYB$DEFAULT_ HEAP 
section 3-11 
CYBIL command 
BINARY_OBJECT 
parameter 8-2 
BINARY parameter 8-2 
DEBUG_AIDS parameter 8-3 
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INDEX 


ERROR_LEVEL 
parameter 8-3 
Example 8-6 
Format 8-1 
INPUT parameter 8-1 
LIST_OPTIONS parameter 8-2 
LIST parameter 8-1 
OPTIMIZATION, LEVEL 
parameter 84; 9-13 
OPTIMIZATION 
parameter 84 
PAD parameter 84 
RUNTIME, CHECKS 
parameter 8-5 
STATUS parameter 8-5 
CYBILrdefined elements 2-1 
CYBIL reserved words C-l 
CYBIL syntax 2-6 
CYCLE statement 
Definition 5-28 
Example 5-29 
Format 5-28 

D 

Data conversion functions 6-1 
Data in memory 
Alignment D-l 
Examples D-2 
Size requirements D-l 
Debug commands 
Debug compiler options 8-3,4 
Debug functions 

$CURRENT_ LINE 9-75 
$CURRENT_ MODULE 9-76 
$CURRENT, 

PROCEDURE 9-77 
$CURRENT_ PVA 9-78 
Overview 9-74 
$PROGRAM_VALUE 9-79 
DEBUG, INPUT attribute 9-3 
DEBUG_MODE attribute 9-3 
DEBUG, OUTPUT attribute 9-3,4 
Debug subcommands 
CHAD 9-22 
CHAM 9-25 

CHANGE,DEFAULT 9-22 
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CHANGE_MEMORY 9-25 
CHANGE, PROGRAM, 
VALUE 9-28 

CHANGE, REGISTER 9-32 
CHAPV 9-28 
CHAR 9-32 
DELB 9-35 

DELETE, BREAK 9-35 
DISB 9-36 
DISC 9-38 
DISDE 941 
DISM 944 

DISPLAY, BREAK 9-36 
DISPLAY, CALL 9-38 
DISPLAY, DEBUGGING, 
ENVIRONMENT 941 
DISPLAY,MEMORY 944 
DISPLAY _ PROGRAM, 
VALUE 948 

DISPLAY, REGISTER 9-51 
DISPLAY _ STACK, 

FRAME 9-54 
DISPV 948 
DISR 9-51 
DISSF 9-54 
QUI 9-58 
QUIT 9-58 
RUN 9-59 
SET, BREAK 9-60 
SET, STEP,MODE 9-70 
SETB 9-60 
SETSM 9-70 
Summary 9-18 
Debug utility 
Accessing 9-2 
Addressing 9-8 
Attributes 9-3,4 
Bound modules 9-13 
Break report message 9-9 
Breaks 9-8,35,36,60 
Call chain 9-38 
Commands, see separate entry 
Condition code 9-7 
Condition handlers 9-14 
Defaults 9-22 
Deferred breaks 9-16 
Ending a session 9-58 
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INDEX 


Environment 941 
Example of batch session 9-92 
Example of interactive 
session 9-82 

Functions, see separate entry 
Input file 9-5,23 
Interrupt processing 9-14 
Multiple breaks 9-17 
Multiring environment 9-17 
Multitask debugging 9-14 
Optimized code 9-13 
Output file 9-6,23 
Overview 9-1 
Product identifier 9-7 
Program addresses 9-8 
Resuming a session 9-59 
Ring 9-16 

Starting a session 9-59 
Status variable 9-7 
Step mode 9-70 
Use 9-82 

Debugging programs, see 
Debug utility 
Decimal notation 24 
Declarations 

Compilation 8-8 
Overview 1-1 
Default heap 3-11 
Defaults, Debug 9-22 
Deferred breaks 9-16 
DELB subcommand 9-35 
DELETE, BREAK 
subcommand 9-35 
Delete Debug breaks 9-35 
Delimiter A4 
Dereference, pointer 4-13 
Diagnostics, listing 8-3 
Digit A4 
Direct pointer 

Byte number 6-25 
Converting from a relative 
pointer 4-18 
#OFFSET function 6-25 
Return ring number 6-28 
Return segment number 6-29 
Ring 6-28 


Segment 6-29 
Signed offset 
(byte number) 6-25 
Directives, compile-time 
COMMENT 8-28 
Comment control 8-28 
COMPILE 8-26 
Definition 8-12 
EJECT 8-20 
General format 8-12 
Layout control 8-19 
LEFT 8-19 

Maintenance control 8-26 
NEWTITLE 8-23 
NOCOMPILE 8-27 
OLDTITLE 8-25 
POP 8-17 
PUSH 8-16 
RESET 8-18 
RIGHT 8-19 
SET 8-13 
SKIP 8-22 
SPACING 8-21 
TITLE 8-24 
Toggle control 8-13 
DISB subcommand 9-36 
DISC subcommand 9-38 
DISDE subcommand 941 
DISM subcommand 944 
DISPLAY, BREAK 
subcommand 9-36 
DISPLAY, CALL 
subcommand 9-38 
Display Debug breaks 9-36 
DISPLAY, DEBUGGING, 
ENVIRONMENT 
subcommand 941 
DISPLAY, MEMORY 
subcommand 944 
DISPLAY, PROGRAM, VALUE 
subcommand 948 
DISPLAY, REGISTER 
subcommand 9-51 
DISPLAY, STACK, FRAME 
subcommand 9-54 
DISPV subcommand 948 
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DISR subcommand 9-51 
DISSF subcommand 9-54 
DIV operator 5-3 
DIVIDE _ FAULT break 9-61 
Division operation 
Integer quotient 5-3 
Real quotient 5-3 
Remainder 5-3 

E 

EJECT directive 8-20 
Elements 

CYBIL-defined 2-1 
Scope of 2-8 
Syntax of 2-6 
User-defined 2-2 
ELSE 5-24,26 
ELSEIF 5-24 
Empty statement 2-7; 5-13 
END 5-16 
Entry point A-4 
Equal to operator 5-6,9 
Equality, set 5-9,12 
Equivalent types 4-2 
Error checking of subranges 4-9 
Error list compiler options 8-3 
Event A4 

Exclusive OR operation 5-5 
Execution 8-1 
EXECUTION break 9-61 
Execution ring A-4 
Execution time A-4 
EXIT statement 
Definition 5-30 
Format 5-30 
Exponent 2-4 

EXPONENT,OVERFLOW 
break 9-61 

EXPONENT, UNDERFLOW 
break 9-61 
Expression 

Compile-time 8-9 
Constant 2-6 
Definition 5-1; A-4 
Operands 5-1 
Operators 5-2 


External reference A-4 
Externally declared variable 

2-9; 3-3 

Externally referenced 
variable 3-3 

F 

FALSE 4-6 

Fatal diagnostics, listing 8-3 
Field 4-28; A4 
Floating-point 
Constant 24 
Type 4-11 

FLOATING_POINT, 
INDEFINITE break 9-61 
FLOATING_POINT_ 
SIGNIFICANCE break 9-62 
FOR statement 
Definition 5-17 
Examples 5-18,19 
Format 5-17 
FOREND 5-17 
Formal parameters 
Function 6-18,19 
Procedure 7-10,11 
Program 2-12 
Reference 2-12 
Value 2-12 
Format 8 

FORMAT, CYBIL, SOURCE 
command 8-7 
Format source code 8-7 
#FREE_ RUNNING, CLOCK 
function 6-24 
Free running microsecond 
clock 6-24 
FREE statement 
Definition 5-39 
Format 5-39 

Functions, see also user-defined 
functions 
#ADDRESS 6-23 
Calling 6-21 
$CHAR 6-2 

$CURRENT_ LINE 9-75 
$CURRENT_ MODULE 9-76 
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$CURRENT_ 
PROCEDURE 9-77 
$CURRENT_PVA 9-78 
Data conversion 6-1 
Definition 6-1 
Format 6-17 
IINTEGER 6-3 
#LOC 64 

LOWERBOUND 6-5 
LOWERVALUE 6-6 
#OFFSET 6-25 
Overview 1-3; 6-1 
Parameters 6-17 
PRED 6-7 

$PROGRAM_ VALUE 9-79 
#PTR 6-8 

#READ_ REGISTER 6-27 
$REAL 6-9 
Recursive 6-1 
#REL 6-10 
#RING 6-28 
#SEGMENT 6-29 
#SEQ 6-11 
#SIZE 6-12 
Standard 6-1 
STRLENGTH 6-13 
SUCC 6-14 

System-dependent 6-1,23 
UPPERBOUND 6-15 
UPPERVALUE 6-16 
User-defined 6-17 

G 

#GATE attribute 34 
Global key 7-15 
Global variable 2-8 
Glossary A-l 

Greater than operator 5-6,9 
Greater than or equal to 
operator 5-6,9 

H 

#HASH_SVA procedure 7-20 


Heap 

Adaptable 447 
Default 3-11 
Definition 441 
Example 5-34 
Format 441 
Management 5-32 

I 

IDENTIFIER field 9-7 
Identity operation 54 
Identity, set 5-9,12 
IF statement 

Compile-time 8-11 
Definition 5-24 
Examples 5-25 
Format 5-24 
IFEND 5-24 

Improper subrange type 4-9 
IN operator 5-6,9,12 
Indefinite value constructor 3-13; 
4-25,35,38 

Inequality, set 5-9,12 
Informative diagnostics, 
listing 8-3 
Initializing 

Array elements 4-25 
Effect of attribute on 3-14 
Record 4-35 
Set elements 4-38 
Variable 34,13 
Input 

Compiler parameter 8-1 
To programs 1-3 
Input file, Debug 9-5,23 
Input/output 7; 1-3 
Integer 

Constant 2-3; A-5 
Definition 44 
Example 44 
Format 44 
Quotient division 5-3 
Range 44 

IINTEGER function 6-3 
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Interactive Debug 
Definition A-5 
Example 9-82 

Interrupt processing, Debug 9-14 
Intersection operation 5-11 
Intersection, set 5-3 
INV ALID_ BDP _ DATA 
break 9-62 
Invariant record 
Definition 4-28 
Example 4-30 
Format 4-28 

J 

Job level specifications 9-3,4 

K 

Keypoint instruction 7-21 
#KEYPOINT procedure 7-21 

L 

Label, statement 5-16,17,20,21,28 
Language syntax 2-6 
Layout control directives 8-19 
LEFT directive 8-19 
Less than operator 5-6,9 
Less than or equal to 
operator 5-6,9 
Lifetime of a variable 3-10 
Line tables 8-3 
LIST toggle 8-14 
LISTALL toggle 8-14 
LISTCTS toggle 8-14 
USTEXT toggle 8-14 
Listing, compiler 
Options 8-2 
Parameter 8-1 
Listing toggles 8-14 
LISTOBJ toggle 8-14 
$LITERAL section 3-11 
Load module A-5 
Load page table index 7-20 
#LOC function 6-4 


Local 

Key 7-15 
Variable 2-8 
Lock variable 7-17 
Logical AND operation 5-3 
Logical OR operation 5-5 
LOWERBOUND function 6-5 
Lowerbounds 4-9 
LOWERVALUE function 6-6 
LPAGE instruction 7-20 

M 

Machine addressing A-5 
Machine code debugging, see 
Debug utility 

Machine-level debugging A-5 
Maintenance control 
directives 8-26 
Manuals, related 2; 9 
Map buffer, purging 7-22 
Margins, set 8-19 
Memory 

Alignment of elements D-l 
Cell D-l 

Change contents during 
debugging 9-25 
Display during debugging 944 
Examples of representation D-2 
Size requirements for 
elements D-l 
MOD operator 5-3 
MODEND format 2-10 
Module A-5 

Addressing A-5 
Declaration 2-10 
Definition 2-8 
Examples 2-10 
Format 2-10 
Level 2-8 
Name 2-10 
Structure 2-8 
MODULE format 2-10 
Multiple breaks 9-17 
Multiplication operation 5-3 
Multiplication operators 5-2 
Multiring environment 9-17 
Multitask debugging 9-14 
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N 

Name 

Definition A-6 
Examples 2-3 
Rules for forming 2-2 
Nearly exhausted resources 9-15 
Negation operation 5-11 
Negation operators 5-2 
NEWTITLE directive 8-23 
NEXT statement 
Definition 5-37 
Format 5-37 

NIL pointer constant 2-4; 4-15 
No-op instructions 8-4 
NOCOMPILE directive 8-27 
NORMAL field 9-7 
Not equal to operator 5-6,9 
NOT operator 5-2 
Null string 2-5 

o 

Object code 

Definition A-6 
Listing 8-2,14 
Object module A-6 
Object of a pointer 4-13 
Offset, byte A-2 
#OFFSET function 6-25 
OLDTTTLE directive 8-25 
Operands 5-1 
Operators 
Addition 5-4 
Definition 5-2 
Multiplication 5-2 
Negation 5-2 
Order of evaluation 5-2 
Relational 5-6 
Set 5-10 
Sign 54 

Optimization compiler options 84; 

9-13 

Optimized code, debugging 9-13 

OR operator 5-5 

Ordinal 

Constant 24 


Definition 4-7 
Examples 4-8 
Format 4-7 
$OUTPUT file 9-6 
Output file, Debug 9-6,23 
Output from programs 1-3 
Overview of language 1-1 


P 

P register 

Change 9-32 
Display 9-51 

Packed elements in memory D-l 
PACKED parameter 
Adaptable arrays 443 
Adaptable records 444 
Arrays 4-24 
Records 4-28,31 
Packing parameter 

Adaptable arrays 443 
Adaptable records 444 
Arrays 4-24 
Records 4-28,31 

Padding compiler parameter 84 
Page A-7 

Page advance directive 8-20 
Page table map 7-22,23 
Page table, see system page table 
Parameter list 2-13; 6-19; 7-11 
$PARAMETER section 3-11 
Parent name 4-18; 6-8,10 
Pause break 9-15 
Performance monitoring 7-21 
Pointer 

Adaptable types 4-15 
Constant 24 
Definition 4-13; A-7 
Dereference 4-13 
Example 4-16 
Format 4-13 
NIL 4-15 
Object 4-13 
Pointer to cell 4-17 
Reference 4-13 
Relative 4-18 
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Pointer to cell 

#ADDRESS function 6-23 
Definition 4-17 

Pointer-to-procedure conversion 
procedure 7-19 
POP directive 8-17 
Potentially equivalent types 4-2 
PRED function 6-7 
Predecessor of an expression 6-7 
Predefined sections 3-11 
Previous save area 6-26 
#PREVIOUS_SAVE_AREA 
function 6-26 

Procedures, see also user-defined 
procedures 
#CALLER_ID 7-15 
Calling 7-13 

#COMPARE_SWAP 7-17 
Definition 7-1 
Format 7-9 
#HASH_SVA 7-20 
#KEYPOINT 7-21 
Overview 1-3; 7-1 
Parameters 7-9 
#PURGE _ BUFFER 7-22 
#SCAN 7-24 
Standard 7-1 
STRINGREP 7-2 
System-dependent 7-15 
#TRANSLATE 7-26 
User-defined 7-9 
#WRITE_REGISTER 7-28 
PROCEND format 2-14 
Process register 
Read 6-27 
Write 7-28 

Process virtual address 24; 6-25; 
9-78 

Processor register 
Read 6-27 
Write 7-28 

Product identifier, Debug 9-7 
Program 

Addresses in Debug 9-8 
Declaration 2-12 
Elements 2-1 
Example 2-14 


Execution 8-1 
Format 2-12 
Input 1-3 
Name 2-12 
Output 1-3 
Structure 2-8 
Syntax 2-6 
Value, change 9-28 
Value, display 948,79 
PROGRAM format 2-12 
Program level specifications 9-3,4 
$PROGRAM_ VALUE 
function 9-79 
#PTR function 4-18; 6-8 
Punctuation 2-7 
Purge 

Cache 7-22 
Instruction 7-22 
Map buffer 7-22 
#PURGE _ BUFFER 
procedure 7-22 
PUSH directive 8-16 
PUSH statement 
Definition 540 
Example 5-34,40 
Format 540 

PVA, see process virtual address 

Q 

QUI subcommand 9-58 
QUIT subcommand 9-58 

R 

Radix 2-3 
Range A-7 
Range checking 

Compiler options 8-5 
Toggles 8-15 
READ attribute 3-3,6 
READ break 9-62 
RE AD_ NEXT_ INSTRUCTION 
break 9-62 
Read-only 

Section 3-6,11,18 
Variable 3-3,6 
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#READ_REGISTER function 6-27 
Real 

Constant 24 
Definition 4-11 
Format 4-11 
Quotient division 5-3 
Range 4-11 
$REAL function 6-9 
Record 

Adaptable 444 
Alignment 4-29,31,37,44 
Bound variant 4-31,33 
Definition 4-28 
Examples 4-30,34,35,36 
Fields 4-28 
Format 4-28,31 
Initializing elements 4-35 
Invariant 4-28 
Referencing elements 4-36 
Variant 4-31 
Reference parameters 
Function 6-18,19 
Procedure 7-10,11 
Program 2-12 
Reference, pointer 4-13 
Referenced addresses 9-11 
Reformat source code 8-7 
$ REGISTER section 3-11 
Registers 

Change contents of 9-32 
Display 9-51 
Read 6-27 
Write 7-28 

#REL function 4-18; 6-10 
Related manuals 2; 9 
Relational operators 5-6 
Relative pointer 

Access object of 6-8 
Converting to direct 
pointer 4-18 
Definition 4-18 
Direct pointer 4-18 
Format 4-18 
#PTR function 6-8 
#REL function 6-10 
Return 6-10 

Remainder division operation 5-3 


REP format 3-13; 4-25 
REPEAT statement 
Definition 5-20 
Example 5-20 
Format 5-20 
Reported addresses 9-9 
Reserved symbols 2-1 
Reserved words 2-l;A-7;C-l 
RESET directive 8-18 
RESET statement 
Definition 5-35 
Example 5-34 
Format for a heap 5-36 
Format for a sequence 5-35 
RETURN statement 
Definition 5-31 
Format 5-31 
RIGHT directive 8-19 
Ring 

Debug 9-16 
Definition A-7 
Level 34 
Number 6-23; 7-15 
Return number in pointer 6-28 
Ring, execution A4 
#RING function 6-28 
RUN subcommand 9-59 
Run-time checking 
Compiler options 8-5 
Toggles 8-15 

Run time, see execution time 
Run-time stack 
management 5-32,40 

S 

Save area 6-26 
Scalar types 4-3 
#SCAN procedure 7-24 
Scientific notation 24 
Scope attributes 3-7 
Scope of elements 2-8 
Section 

Attribute 34,11 
Declaration 3-18 
Definition 3-11,18; A-8 
Example 3-19 
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Format 3-18 
Map 9-13 
Name 34,11 
Predefined names 3-11 
SECTION format 3-18 
Segment 

Definition A-8 
Number 6-23; 7-15 
Return number in pointer 6-29 
#SEGMENT function 6-29 
Segment table map 7-23 
Semicolon 2-7 
#SEQ function 6-11 
Sequence 

Adaptable 446 
Definition 440 
Format 440 
Management 5-32 
Return pointer to 6-11 
#SEQ function 6-11 
Set 

Complement 54,11 
Containment 5-12 
Difference 5-5,11 
Equality 5-9,12 
Identity 5-6,9,12 
Inclusion 5-12 
Inequality 5-6,9,12 
Intersection 5-3,11 
Membership 5-6,9,12 
Negation 5-11 
Operators 5-10 
Subset 56,9 
Superset 56,9 
Symmetric difference 5-11 
Union 56,11 

SET_ BREAK subcommand 960 
SET directive 8-13 
SET _ STEP _ MODE 
subcommand 9-70 
Set type 

Assigning elements 4-38 
Definition 4-38 
Example 4-39 
Format 4-38 

Initializing elements 468 


Set value constructor 
Definition 469 
Format 469 
SETB subcommand 960 
SETSM subcommand 9-70 
Sign inversion 54 
Sign operators 54 
Size fixer 563 
#SIZE function 6-12 
SKIP directive 8-22 
Source 
Code A6 
listing 8-2 
Text input 8-1 
Source code 
Reformat 8-7 

Source code debugging, see Debug 
utility 

Spaces in syntax 26 
Spacing 2-7 

SPACING directive 8-21 
SPT, see system page table 
Stack frame 6-26 
Stack frame, display 964 
Stack frame save area 6-26 
$STACK section 3-11 
Stack, see run-time stack 
management 
Standard functions 6-1 
Standard procedures 7-1 
Statements) 

ALLOCATE 5-38 
Assignment 5-13 
BEGIN 5-16 
CASE 5-26 
Compilation 86 
Control 5-23 
CYCLE 5-28 
Definition 5-13 
Empty 2-7; 5-13 
EXIT 560 
FOR 5-17 
FREE 569 
IF 5-24 

Label 5-16,17,20,21,28 
List 5-13,16; A6 
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NEXT 5-37 
Overview 1-1,2 
PUSH 540 
REPEAT 5-20 
RESET 5-35 
RETURN 5-31 
Storage management 5-32 
Structured 5-16 
WHILE 5-21 

STATIC attribute 2-9; 34,9 
$STATIC section 3-11 
Static variable 2-9; 3-9 
Status variable 
Compiler call 8-5 
CYBIL command 8-5 
Debug 9-7 

FORMAT. CYBIL. SOURCE 
command 8-7 
Step mode, Debug 9-70 
Storage allocation 2-9 
Storage attributes 3-9 
Storage management statements 
ALLOCATE 5-38 
Examples 5-34 
FREE 5-39 
NEXT 5-37 
Overview 5-32 
PUSH 540 
RESET 5-35 
Storage types 440 
String 

Adaptable 442 
Assigning 4-23 
Comparing 4-23 
Constant 2-5; A-8 
Definition 4-19 
Examples 4-22,23 
Format 4-19 
Length 6-13 

STRLENGTH function 6-13 
Substring 2-5; 4-20 
STRINGREP procedure 
Boolean element 74 
Character element 7-3 
Definition 7-2 
Floating-point element 7-5 
Format 7-2 


Integer element 7-3 
Ordinal element 74 
Pointer element 7-8 
String element 7-8 
Subrange element 74 
STRLENGTH function 6-13 
Structured statements 
BEGIN 5-16 
FOR 5-17 
Overview 5-16 
REPEAT 5-20 
WHILE 5-21 
Structured types 4-19 
Subrange 

Definition 4-9 
Error checking 4-9 
Example 4-10 
Format 4-9 
Subscript bounds 4-24 
Subset of a set 5-6,9 
Substring 

Definition 4-20 
Examples 4-22 
Format 4-20 
Of a string constant 2-5 
Subtraction operation 5-5 
SUCC function 6-14 
Successor of an expression 6-14 
Superset of a set 5-6,9 
SVA, see system virtual address 
Symbol tables 8-3 
Symbolic 

Addressing A-8 
Cross-reference listing 8-2 
Debugging A-8 
Symbols, reserved 2-1 
Symmetric difference 5-5 
Symmetric difference 
operation 5-11 
Syntax 2-6 
System-dependent 
Functions 6-23 
Procedures 7-15 
System-dependent 
functions 6-1 
System page table 7-20 
System virtual address 7-20 


Revision D 


CYBIL Language Definition Index-13 


INDEX 


T 

Tag field 

Definition 4-31,32 
Size 5-33 

Terminate break 9-15 
TEXT field 9-7 
TITLE directive 8-24 
Titles 8-23,24,25 
Toggle control directives 
Definition 8-13 
Listing toggles 8-14 
Run-time checking toggles 8-15 
Traceback A-8 

#TRANSLATE procedure 7-26 
Translation table 7-26 
Trap interrupts 7-21 
TRUE 4-6 
Type 

Declaration 3-16 
Examples 3-16 
Format 3-16 
TYPE format 3-16 
Types 4-1 

Adaptable 442 
Adaptable array 443 
Adaptable heap 447 
Adaptable record 444 
Adaptable sequence 446 
Adaptable string 442 
Array 4-24 
Basic 4-3 
Boolean 4-6 
Cell 4-12 
Character 4-5 
Equivalent 4-2 
Floating-point 4-11 
Formats for using 4-2 
Heap 441 
Integer 44 
Ordinal 4-7 
Overview 1-1; 4-1 
Pointer 4-13 
Pointer to cell 4-17 
Potentially equivalent 4-2 
Real 4-11 


Record 4-28 
Relative pointer 4-18 
Scalar 4-3 
Sequence 440 
Set 4-38 
Storage 440 
String 4-19 
Structured 4-19 
Subrange 4-9 

u 

#UNCHECKED_ CONVERSION 
procedure 7-27 
Union operation 5-11 
Union, set 5-5 
Unpacked elements in 
memory D-l 
UNTIL 5-20 

UPPERBOUND function 6-15 
Upperbounds 4-9 
UPPERVALUE function 6-16 
User-defined elements 
Constants 2-3 
Definition 2-2 
User-defined functions 

Actual parameters 6-19,21 
Attributes 6-17 
Calling 6-21 
Examples 6-20,22 
Formal parameters 6-18,19 
Format 6-17 
Parameters 6-17,19 
Reference parameters 6-18,19 
Value parameters 6-18,19 
User-defined procedures 

Actual parameters 7-11,13 
Attributes 7-9 
Calling 7-13 
Examples 7-12,14 
Formal parameters 7-10,11 
Format 7-9 
Parameters 7-9,11 
Reference parameters 7-10,11 
Value parameters 7-10,12 
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Value constructor, see indefinite 
value constructor 
Value parameters 
Function 6-18,19 
Procedure 7-10,12 
Program 2-12 
VAR format 3-3 
Variable A-9 

Attributes 3-3,6; A-9 
Automatic 2-9; 3-9 
Compile-time 8-8 
Declaration 3-3 
Definition 3-3 
Examples 3-5,7,8,10,12,15 
Format 3-3 
Global 2-8 
Initialization 3-4,13 
Lifetime 3-10 
Local 2-8 
Read-only 3-3,6 
Static 2-9; 3-9 
Types 4-1 
Variant record 
Bound 4-31,33 


Definition 4-30 
Example 4-34 
Format 4-30 


W 

Warning diagnostics, fisting 8-3 
WHILE statement 
Definition 5-21 
Example 5-22 
Format 5-21 
WHILEND 5-21 
Words, reserved 2-l;A-7;C-l 
WRITE break 9-62 
# WRITE _ REGISTER 
procedure 7-28 

X 

X registers 
Change 9-32 
Display 9-51 
XDCL attribute 2-9; 3-3,7 
XOR operator 5-5 
XREF attribute 3-3,7 
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We would like your comments on this manual. While writing it, we made some assumptions about who would use it 
and how it would be used. Your comments will help us improve this manual. Please take a few minutes to reply. 


Who Are You? 

How Do You Use This Manual? 

Which Do You Also Have? 

□ Manager 

□ Systems Analyst or Programmer 

□ Applications Programmer 

□ Operator 

□ Other 

□ As an Overview 

□ To Learn the Product/System 

□ For Comprehensive Reference 

□ For Quick Look-up 

□ Any SCL Manuals 

□ CYBIL File Interface 

□ CYBIL System Interface 


What programming languages do you use? _ 

Which are helpful to you? □ Procedures Index (inside covers) □ Glossary □ Related Manuals page 
□ Character Set □ Other: _ 


How Do You Like This Manual? Check those that apply. 


Yes 

Somewhat 

No 


□ 

□ 

□ 

Is the manual easy to read (print size, page layout, and so on)? 

□ 

□ 

□ 

Is it easy to understand? 

□ 

□ 

□ 

Is the order of topics logical? 

□ 

□ 

□ 

Are there enough examples? 

□ 

□ 

□ 

Are the examples helpful? (□ Too simple □ Too complex) 

□ 

□ 

□ 

Is the technical information accurate? 

□ 

□ 

□ 

Can you easily find what you want? 

□ 

□ 

□ 

Do the illustrations help you? 

□ 

□ 

□ 

Does the manual tell you what you need to know about the topic? 


Comments? If applicable, note page number and paragraph. 


Would you like a reply? □ Yes □ No Continue on other side 
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Date _ ... . 
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Keyword Index 


ARRAY (adaptable).4-43 

ARRAY (fixed).4-24 

BOOLEAN .4-6 

CELL.4-12 

CHAR.4-5 

CONST.3-1 

FUNCEND.6-17 

FUNCTION .6-17 

HEAP (adaptable).4-47 

HEAP (fixed).4-41 

INTEGER.4-4 

MODEND .2-10 

MODULE.2-10 

Ordinal.4-7 

Pointer.4-13 

PROCEDURE.7-9 

PROCEND (for a procedure) ... 7-9 

Statement Index _ 

ALLOCATE .5-38 

Assignment.5-13 

BEGIN.5-16 

CASE.5-26 

CYCLE.5-28 

EXIT.5-30 

FOR.5-17 

FREE.5-39 


PROCEND (for a program) ... 2-14 


PROGRAM.2-12 

REAL .4-11 

RECORD (adaptable).4-44 

RECORD (invariant).4-28 

RECORD (variant).4-30 

REL.4-18 

SECTION.3-18 

SET.4-38 

SEQ (adaptable).4-46 

SEQ (fixed).4-40 

STRING (adaptable).4-42 

STRING (fixed).4-19 

Subrange .4-9 

TYPE.3-16 

VAR.3-3 


IF.5-24 

NEXT.5-37 

PUSH .5-40 

REPEAT.5-20 

RESET (in a heap).5-36 

RESET (in a sequence).5-35 

RETURN.5-31 

WHILE.5-21 


Function Index 


# ADDRESS.6-23 

$CHAR.6-2 

#FREE_RUNNING_ 

CLOCK .6-24 

FUNCEND.6-17 

FUNCTION .6-17 

$INTEGER.6-3 

# LOC.6-4 

LOWERBOUND.6-5 

LOWERVALUE.6-6 

#OFFSET.6-25 

PRED .6-7 

#PREVTOUS_SAVE_ 

AREA.6-26 


#PTR.6-8 

#READ_REGISTER.6-27 

SREAL .6-9 

#REL.6-10 

#RING.6-28 

#SEGMENT.6-29 

#SEQ.6-11 

#SIZE.6-12 

STRLENGTH.6-13 

SUCC .6-14 

UPPERBOUND.6-15 

UPPERVALUE.6-16 

User-defined functions.6-17 
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Procedure Index 


#CALLER ID. 

.7-15 

#PURGE BUFFER. 

... 7-22 

^COMPARE SWAP. 

.7-17 

#SCAN. 

... 7-24 

#CONVERT POINTER_TO_ 


STRINGREP. 

.... 7-2 

PROCEDURE . 

.7-19 

# TRANSLATE. 

... 7-26 

#HASH SVA . 

.7-20 

#UNCHECKED_ 


#KEYPOINT. 

.7-21 

CONVERSION. 

... 7-27 

PROCEDURE. 

..7-9 

User-defined procedures_ 

.... 7-9 

PROCEND. 

..7-9 

#WRITE REGISTER. 

... 7-28 


Compilation Index 


COMMENT directive. 

.8-28 

OLDTTTLE directive. 

.8-25 

COMPILE directive . 

.8-26 

POP directive . 

.8-17 

CYBIL command. 

..8-1 

PUSH directive. 

.8-16 

EJECT directive. 
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